@shopify/ui-extensions 2023.4.0 → 2023.4.1

package/src/surfaces/admin/api/standard/standard.ts

@@ -1,14 +1,29 @@
-import type {StandardApi as BaseStandardApi, I18n} from '../../../../api';
-import type {ExtensionPoint as AnyExtensionPoint} from '../../extension-points';
+import type {
+  StandardApi as BaseStandardApi,
+  I18n,
+  Intents,
+  Navigation,
+} from '../../../../api';
+import type {ExtensionTarget as AnyExtensionTarget} from '../../extension-targets';
 
 /**
- * The following APIs are provided to all extension points.
+ * The following APIs are provided to all extension targets.
  */
-export interface StandardApi<ExtensionPoint extends AnyExtensionPoint>
+export interface StandardApi<ExtensionTarget extends AnyExtensionTarget>
   extends BaseStandardApi {
   /**
-   * The identifier of the running extension point.
+   * The identifier of the running extension target.
    */
-  extensionPoint: ExtensionPoint;
+  extension: {
+    target: ExtensionTarget;
+  };
   i18n: I18n;
+  /**
+   * Provides information to the receiver the of an intent.
+   */
+  intents: Intents;
+  /**
+   * Provides methods to navigate to other features in the Admin.
+   */
+  navigation: Navigation;
 }

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

@@ -2,10 +2,11 @@ import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
 
 const data: ReferenceEntityTemplateSchema = {
   name: 'AdminAction',
+  featureFlag: 'admin_extensibility',
   description:
     'AdminAction is a component used by Admin Action extensions to configure a primary and secondary action and title.',
   requires: '',
-  thumbnail: 'appaction-thumbnail.png',
+  thumbnail: 'adminaction-thumbnail.png',
   isVisualComponent: true,
   type: '',
   definitions: [
@@ -18,7 +19,7 @@ const data: ReferenceEntityTemplateSchema = {
   category: 'Components',
   subCategory: 'Other',
   defaultExample: {
-    image: 'appaction-default.png',
+    image: 'adminaction-default.png',
     codeblock: {
       title: 'Set the primary and secondary action of the Action modal.',
       tabs: [
@@ -35,7 +36,13 @@ const data: ReferenceEntityTemplateSchema = {
       ],
     },
   },
-  related: [],
+  related: [
+    {
+      type: 'component',
+      name: 'AdminBlock',
+      url: '/docs/api/admin-extensions/components/other/adminblock',
+    },
+  ],
 };
 
 export default data;

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

@@ -16,8 +16,6 @@ export interface AdminActionProps {
    * Sets the Secondary action button of the container. This component must a button component.
    */
   secondaryAction?: RemoteFragment;
-
-  children: any;
 }
 /**
  * AdminAction is a component used by Admin Action extensions to configure a primary and secondary action and title.

package/src/surfaces/admin/components/AdminAction/examples/basic-adminaction.example.ts

@@ -1,14 +1,20 @@
 import {extension, AdminAction, Button} from '@shopify/ui-extensions/admin';
 
 export default extension('Playground', (root) => {
+  const primaryAction = root.createFragment();
+  const secondaryAction = root.createFragment();
+
+  primaryAction.appendChild(
+    root.createComponent(Button, {onPress: () => {}}, 'Action')
+  );
+  secondaryAction.appendChild(
+    root.createComponent(Button, {onPress: () => {}}, 'Secondary')
+  );
+
   const adminAction = root.createComponent(AdminAction, {
     title: 'My App Action',
-    primaryAction: root.createFragment(
-      root.createComponent(Button, {onPress: () => {}}, 'Action')
-    ),
-    secondaryAction: root.createFragment(
-      root.createComponent(Button, {onPress: () => {}}, 'Secondary')
-    )
+    primaryAction,
+    secondaryAction,
   }, 'Modal content');
 
   root.appendChild(adminAction);

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

@@ -2,10 +2,11 @@ import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
 
 const data: ReferenceEntityTemplateSchema = {
   name: 'AdminBlock',
+  featureFlag: 'admin_extensibility',
   description:
     'This component is similar to the AdminBlock, providing a deeper integration with the container your UI is rendered into. However, this only applies to Block Extensions which render inline on a resource page.',
   requires: '',
-  thumbnail: 'appblock-thumbnail.png',
+  thumbnail: 'adminblock-thumbnail.png',
   isVisualComponent: true,
   type: '',
   definitions: [
@@ -18,7 +19,7 @@ const data: ReferenceEntityTemplateSchema = {
   category: 'Components',
   subCategory: 'Other',
   defaultExample: {
-    image: 'appblock-default.png',
+    image: 'adminblock-default.png',
     codeblock: {
       title: 'Simple AdminBlock implementation',
       tabs: [
@@ -35,7 +36,13 @@ const data: ReferenceEntityTemplateSchema = {
       ],
     },
   },
-  related: [],
+  related: [
+    {
+      type: 'component',
+      name: 'Adminaction',
+      url: '/docs/api/admin-extensions/components/other/adminaction',
+    },
+  ],
 };
 
 export default data;

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

@@ -10,8 +10,6 @@ export interface AdminBlockProps {
    * The summary to display when the app block is collapsed. If not provided, no summary will be displayed. No summary is shown when the app block is expanded.
    */
   summary?: string;
-
-  children: any;
 }
 
 export const AdminBlock = createRemoteComponent<'AdminBlock', AdminBlockProps>(

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

@@ -2,6 +2,7 @@ import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
 
 const data: ReferenceEntityTemplateSchema = {
   name: 'BlockStack',
+  featureFlag: 'admin_extensibility',
   description:
     "This structures layout elements along the vertical axis of the page. It's useful for vertical alignment.",
   requires: '',
@@ -36,7 +37,13 @@ const data: ReferenceEntityTemplateSchema = {
     },
   },
 
-  related: [],
+  related: [
+    {
+      type: 'component',
+      name: 'InlineStack',
+      url: '/docs/api/admin-extensions/components/structure/Stack',
+    },
+  ],
 };
 
 export default data;

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

@@ -6,6 +6,8 @@ import {
   SizingProps,
   PaddingProps,
   GapProps,
+  CrossAxisAlignment,
+  MainAxisAlignment,
 } from '../shared';
 
 export interface BlockStackProps
@@ -20,6 +22,20 @@ export interface BlockStackProps
    * provide them with more context.
    */
   accessibilityLabel?: string;
+
+  /**
+   * Position children along the main axis
+   *
+   * @defaultValue 'start'
+   */
+  inlineAlignment?: CrossAxisAlignment;
+
+  /**
+   * Position children along the cross axis
+   *
+   * @defaultValue 'start'
+   */
+  blockAlignment?: MainAxisAlignment;
 }
 
 export const BlockStack = createRemoteComponent<'BlockStack', BlockStackProps>(

package/src/surfaces/admin/components/BlockStack/examples/basic-blockstack.example.ts

@@ -9,7 +9,7 @@ export default extension(
     const blockStack = root.createComponent(
       BlockStack,
       {
-        gap: 'base',
+        gap: true,
       },
       [
         root.createText('Child 1'),

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

@@ -2,6 +2,7 @@ import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
 
 const data: ReferenceEntityTemplateSchema = {
   name: 'Box',
+  featureFlag: 'admin_extensibility',
   description:
     'This is your foundational structural element for composing UI. It can be styled using predefined tokens. Use it to build your layout.',
   requires: '',

package/src/surfaces/admin/components/Box/examples/basic-box.example.ts

@@ -3,7 +3,7 @@ import {extend, Box} from '@shopify/ui-extensions/admin';
 extend('Playground', (root) => {
   const box = root.createComponent(
     Box,
-    {border: 'base', padding: 'base'},
+    {padding: 'base'},
     'Box',
   );
 

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

@@ -2,6 +2,7 @@ import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
 
 const data: ReferenceEntityTemplateSchema = {
   name: 'Button',
+  featureFlag: 'admin_extensibility',
   description:
     'Use this component when you want to provide users the ability to perform specific actions, like saving data.',
   requires: '',
@@ -35,7 +36,18 @@ const data: ReferenceEntityTemplateSchema = {
       ],
     },
   },
-  related: [],
+  related: [
+    {
+      type: 'component',
+      name: 'Pressable',
+      url: '/docs/api/admin-extensions/components/actions/pressable',
+    },
+    {
+      type: 'component',
+      name: 'Link',
+      url: '/docs/api/admin-extensions/components/actions/link',
+    },
+  ],
 };
 
 export default data;

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

@@ -2,6 +2,7 @@ import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
 
 const data: ReferenceEntityTemplateSchema = {
   name: 'Checkbox',
+  featureFlag: 'admin_extensibility',
   description:
     'Use this component when you want to provide users with a clear selection option, such as for agreeing to terms and conditions or selecting multiple options from a list.',
   requires: '',
@@ -36,7 +37,13 @@ const data: ReferenceEntityTemplateSchema = {
     },
   },
 
-  related: [],
+  related: [
+    {
+      type: 'component',
+      name: 'ChoiceList',
+      url: '/docs/api/admin-extensions/components/forms/choicelist',
+    },
+  ],
 };
 
 export default data;

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

@@ -2,6 +2,7 @@ import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
 
 const data: ReferenceEntityTemplateSchema = {
   name: 'Divider',
+  featureFlag: 'admin_extensibility',
   description:
     'Use this to create a clear visual separation between different elements in your user interface.',
   requires: '',
@@ -20,7 +21,7 @@ const data: ReferenceEntityTemplateSchema = {
   defaultExample: {
     image: 'divider-default.png',
     codeblock: {
-      title: 'TODO: add example title',
+      title: 'Simple Divider example',
       tabs: [
         {
           title: 'React',

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

@@ -4,9 +4,10 @@ export interface DividerProps {
   /**
    * Specify the direction of the divider.
    *
-   * @defaultValue 'horizontal'
+   * @defaultValue 'inline'
+   * @defaultValue 'inline'
    */
-  direction?: 'horizontal' | 'vertical';
+  direction?: 'inline' | 'block';
 }
 
 export const Divider = createRemoteComponent<'Divider', DividerProps>(

package/src/surfaces/admin/components/Divider/examples/basic-divider.example.ts

@@ -7,8 +7,8 @@ import {
     'Playground',
     (root) => {
       const divier = root.createComponent(Divider);
-      const firstText = root.createText('First Text'),
-      const secondText = root.createText('Second Text'),
+      const firstText = root.createText('First Text');
+      const secondText = root.createText('Second Text');
 
       root.appendChild(firstText);
       root.appendChild(divier);

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

@@ -2,6 +2,7 @@ import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
 
 const data: ReferenceEntityTemplateSchema = {
   name: 'EmailField',
+  featureFlag: 'admin_extensibility',
   description: 'Use this when you need users to provide their email addresses.',
   requires: '',
   thumbnail: 'emailfield-thumbnail.png',
@@ -19,7 +20,7 @@ const data: ReferenceEntityTemplateSchema = {
   defaultExample: {
     image: 'emailfield-default.png',
     codeblock: {
-      title: 'TODO: add example title',
+      title: 'Simple EmailField example',
       tabs: [
         {
           title: 'React',
@@ -34,8 +35,18 @@ const data: ReferenceEntityTemplateSchema = {
       ],
     },
   },
-
-  related: [],
+  related: [
+    {
+      type: 'component',
+      name: 'TextField',
+      url: '/docs/api/admin-extensions/components/forms/textfield',
+    },
+    {
+      type: 'component',
+      name: 'NumberField',
+      url: '/docs/api/admin-extensions/components/forms/numberfield',
+    },
+  ],
 };
 
 export default data;

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

@@ -2,6 +2,7 @@ import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
 
 const data: ReferenceEntityTemplateSchema = {
   name: 'Form',
+  featureFlag: 'admin_extensibility',
   description:
     'Use this component when you want to collect input from users. It provides a structure for various input fields and controls, such as text fields, checkboxes, and buttons. It also handles form submission and reset actions.',
   requires: '',
@@ -35,7 +36,28 @@ const data: ReferenceEntityTemplateSchema = {
       ],
     },
   },
-  related: [],
+  related: [
+    {
+      type: 'component',
+      name: 'TextField',
+      url: '/docs/api/admin-extensions/components/forms/textfield',
+    },
+    {
+      type: 'component',
+      name: 'NumberField',
+      url: '/docs/api/admin-extensions/components/forms/numberfield',
+    },
+    {
+      type: 'component',
+      name: 'EmailField',
+      url: '/docs/api/admin-extensions/components/forms/emailfield',
+    },
+    {
+      type: 'component',
+      name: 'ChoiceList',
+      url: '/docs/api/admin-extensions/components/forms/choicelist',
+    },
+  ],
 };
 
 export default data;

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

@@ -21,12 +21,12 @@ export interface FormProps {
   /**
    * A callback that is run when the form is submitted.
    */
-  onSubmit?(values: Record<string, string | string[]>): void | Promise<void>;
+  onSubmit(): void | Promise<void>;
 
   /**
-   * A callback that is run when the form is resetted.
+   * A callback that is run when the form is reset.
    */
-  onReset?(): void | Promise<void>;
+  onReset(): void | Promise<void>;
 }
 
 export const Form = createRemoteComponent<'Form', FormProps>('Form');

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

@@ -10,11 +10,12 @@ extend('admin.product-details.block.render', (root) => {
   const textField = root.createComponent(
     TextField,
     {
+      label: 'name',
       value: name,
-      onChange = (value) => {
+      onChange: (value) => {
         textField.updateProps({value});
         name = value;
-      }
+      },
     }
   );
 
@@ -22,14 +23,15 @@ extend('admin.product-details.block.render', (root) => {
     // API call to save the values
     const res = await fetch('/save', {method:'POST', body: JSON.stringify({name})});
     if (!res.ok) {
+      const json = await res.json();
       // The Host can catch these errors and do something with them.
-      throw Error(`There were errors: ${res.errors.join(',')}`);
+      throw Error(`There were errors: ${json.errors.join(',')}`);
     }
-  }
+  };
 
   const onReset = async () => {
     name = '';
-  }, []);
+  };
 
   const form = root.createComponent(
     Form,
@@ -38,4 +40,4 @@ extend('admin.product-details.block.render', (root) => {
 
   form.appendChild(textField);
   root.appendChild(form);
-};
+});

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

@@ -2,6 +2,7 @@ import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
 
 const data: ReferenceEntityTemplateSchema = {
   name: 'Heading',
+  featureFlag: 'admin_extensibility',
   description:
     "Use this to display a title. It's similar to the h1-h6 tags in HTML",
   requires: '',
@@ -20,7 +21,7 @@ const data: ReferenceEntityTemplateSchema = {
   defaultExample: {
     image: 'heading-default.png',
     codeblock: {
-      title: 'TODO: add example title',
+      title: 'Simple Heading example',
       tabs: [
         {
           title: 'React',
@@ -36,7 +37,18 @@ const data: ReferenceEntityTemplateSchema = {
     },
   },
 
-  related: [],
+  related: [
+    {
+      type: 'component',
+      name: 'Text',
+      url: '/docs/api/admin-extensions/components/titles-and-text/text',
+    },
+    {
+      type: 'component',
+      name: 'HeadingGroup',
+      url: '/docs/api/admin-extensions/components/titles-and-text/headinggroup',
+    },
+  ],
 };
 
 export default data;

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

@@ -2,6 +2,7 @@ import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
 
 const data: ReferenceEntityTemplateSchema = {
   name: 'HeadingGroup',
+  featureFlag: 'admin_extensibility',
   description:
     'This groups headings together, much like the hgroup element in HTML.',
   requires: '',
@@ -20,7 +21,7 @@ const data: ReferenceEntityTemplateSchema = {
   defaultExample: {
     image: 'headinggroup-default.png',
     codeblock: {
-      title: 'TODO: add example title',
+      title: 'Simple HeadingGroup example',
       tabs: [
         {
           title: 'React',
@@ -36,7 +37,13 @@ const data: ReferenceEntityTemplateSchema = {
     },
   },
 
-  related: [],
+  related: [
+    {
+      type: 'component',
+      name: 'Heading',
+      url: '/docs/api/admin-extensions/components/titles-and-text/heading',
+    },
+  ],
 };
 
 export default data;

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

@@ -5,7 +5,7 @@ import {
     BlockStack,
   } from '@shopify/ui-extensions/admin';
 
-  extend('Checkout::Dynamic::Render', (root) => {
+  extend('Playground', (root) => {
     const headingGroup = root.createComponent(BlockStack, undefined, [
       root.createComponent(Heading, undefined, 'Heading <h1>'),
       root.createComponent(HeadingGroup, undefined, [

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

@@ -2,6 +2,7 @@ import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
 
 const data: ReferenceEntityTemplateSchema = {
   name: 'Icon',
+  featureFlag: 'admin_extensibility',
   description:
     'This component renders an icon from a predefined list. Choose the one that suits your needs.',
   requires: '',
@@ -14,13 +15,18 @@ const data: ReferenceEntityTemplateSchema = {
       description: '',
       type: 'IconProps',
     },
+    {
+      title: 'IconName',
+      description: 'List of available Icons for the Icon component',
+      type: 'IconName',
+    },
   ],
   category: 'Components',
   subCategory: 'Media',
   defaultExample: {
     image: 'icon-default.png',
     codeblock: {
-      title: 'TODO: add example title',
+      title: 'Simple Icon example',
       tabs: [
         {
           title: 'React',
@@ -35,8 +41,34 @@ const data: ReferenceEntityTemplateSchema = {
       ],
     },
   },
-
-  related: [],
+  subSections: [
+    {
+      type: 'Generic',
+      title: 'Available Icons',
+      anchorLink: 'availableIcons',
+      sectionContent:
+        'The available Icons are a 1:1 map of what Icons are available in Polaris. You can find the full list of Icons in the [Polaris Icons documentation](https://polaris.shopify.com/icons).',
+      sectionCard: [
+        {
+          type: 'information',
+          name: 'Polaris Icons',
+          url: 'https://polaris.shopify.com/icons',
+        },
+      ],
+    },
+  ],
+  related: [
+    {
+      type: 'component',
+      name: 'Image',
+      url: '/docs/api/admin-extensions/components/media/image',
+    },
+    {
+      type: 'component',
+      name: 'Image',
+      url: '/docs/api/admin-extensions/components/media/image',
+    },
+  ],
 };
 
 export default data;

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

@@ -1,4 +1,5 @@
 import {createRemoteComponent} from '@remote-ui/core';
+import {IconName} from './IconName';
 
 export interface IconProps {
   /*
@@ -36,7 +37,8 @@ export interface IconProps {
   /*
    * Specifies the name of the icon that will be displayed.
    */
-  name: string;
+  name: IconName;
 }
+export type {IconName};
 
 export const Icon = createRemoteComponent<'Icon', IconProps>('Icon');