@shopify/ui-extensions 2023.7.2 → 2024.1.0

package/src/surfaces/admin/components/DatePicker/examples/basic-datepicker.example.ts

@@ -0,0 +1,11 @@
+import {extend, DatePicker} from '@shopify/ui-extensions/admin';
+
+extend('Playground', (root) => {
+  const datePicker = root.createComponent(
+    DatePicker,
+    {},
+    'DatePicker',
+  );
+
+  root.appendChild(datePicker);
+});

package/src/surfaces/admin/components/DatePicker/examples/multiple-datepicker.example.ts

@@ -0,0 +1,11 @@
+import {extend, DatePicker} from '@shopify/ui-extensions/admin';
+
+extend('Playground', (root) => {
+  const datePicker = root.createComponent(
+    DatePicker,
+    { selected: ['2023-11-08'] },
+    'DatePicker',
+  );
+
+  root.appendChild(datePicker);
+});

package/src/surfaces/admin/components/DatePicker/examples/range-datepicker.example.ts

@@ -0,0 +1,11 @@
+import {extend, DatePicker} from '@shopify/ui-extensions/admin';
+
+extend('Playground', (root) => {
+  const datePicker = root.createComponent(
+    DatePicker,
+    { selected: {start: '2023-11-08', end: '2023-11-10' } },
+    'DatePicker',
+  );
+
+  root.appendChild(datePicker);
+});

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

@@ -2,7 +2,6 @@ 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: '',

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

@@ -2,7 +2,6 @@ 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',

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

@@ -2,9 +2,8 @@ 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.',
+    '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 integrates with the native Contextual Save Bar to handle form submission and reset actions.',
   requires: '',
   thumbnail: 'form-thumbnail.png',
   isVisualComponent: true,

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

@@ -2,7 +2,6 @@ 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: '',

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

@@ -2,7 +2,6 @@ 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: '',

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

@@ -2,7 +2,6 @@ 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: '',
@@ -63,11 +62,6 @@ const data: ReferenceEntityTemplateSchema = {
       name: 'Image',
       url: '/docs/api/admin-extensions/components/media/image',
     },
-    {
-      type: 'component',
-      name: 'Image',
-      url: '/docs/api/admin-extensions/components/media/image',
-    },
   ],
 };
 

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

@@ -1,15 +1,9 @@
 import {createRemoteComponent} from '@remote-ui/core';
 import {IconName} from './IconName';
+import {AccessibilityLabelProps} from '../shared';
 
-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;
-
-  /*
+export interface IconProps extends AccessibilityLabelProps {
+  /**
    * Set the color of the icon.
    *
    * - `inherit` will take the color value from its parent,
@@ -34,7 +28,7 @@ export interface IconProps {
      */
     | 'fill';
 
-  /*
+  /**
    * Specifies the name of the icon that will be displayed.
    */
   name: IconName;

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

@@ -2,7 +2,6 @@ import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
 
 const data: ReferenceEntityTemplateSchema = {
   name: 'Image',
-  featureFlag: 'admin_extensibility',
   description: 'Use this when you want to display an image.',
   requires: '',
   thumbnail: 'image-thumbnail.png',

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

@@ -2,7 +2,6 @@ import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
 
 const data: ReferenceEntityTemplateSchema = {
   name: 'InlineStack',
-  featureFlag: 'admin_extensibility',
   description:
     "Use this to organize layout elements along the horizontal axis of the page. It's great for horizontal alignment.",
   requires: '',

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

@@ -8,21 +8,16 @@ import {
   GapProps,
   CrossAxisAlignment,
   MainAxisAlignment,
+  AccessibilityLabelProps,
 } from '../shared';
 
 export interface InlineStackProps
   extends AccessibilityRoleProps,
+    AccessibilityLabelProps,
     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;
-
   /**
    * Position children along the main axis
    *

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

@@ -0,0 +1,68 @@
+import {createRemoteComponent} from '@remote-ui/core';
+
+export type CustomerSegmentTemplateIcon =
+  | 'categoriesMajor'
+  | 'firstVisitMajor'
+  | 'heartMajor'
+  | 'marketingMajor'
+  | 'checkoutMajor'
+  | 'ordersMajor'
+  | 'locationMajor'
+  | 'emailNewsletterMajor'
+  | 'firstOrderMajor'
+  | 'billingStatementDollarMajor'
+  | 'diamondAlertMajor'
+  | 'abandonedCartMajor'
+  | 'calendarMajor'
+  | 'productsMajor'
+  | 'globeMajor'
+  | 'flagMajor'
+  | 'uploadMajor'
+  | 'buyButtonMajor'
+  | 'followUpEmailMajor'
+  | 'confettiMajor'
+  | 'viewMajor';
+
+export type CustomerSegmentTemplateCategory =
+  | 'firstTimeBuyers'
+  | 'highValueCustomers'
+  | 'reEngageCustomers'
+  | 'abandonedCheckout'
+  | 'purchaseBehaviour'
+  | 'location';
+
+/**
+ * Reserved namespace and key for the customer standard metafield used in the template's query.
+ * More info - https://shopify.dev/docs/apps/custom-data/metafields/definitions/standard
+ */
+type CustomerStandardMetafieldDependency = 'facts.birth_date';
+
+export interface InternalCustomerSegmentTemplateProps {
+  /* Localized title of the template. */
+  title: string;
+  /* Localized description(s) of the template. */
+  description: string | string[];
+  /* Icon identifier for the template. */
+  icon: CustomerSegmentTemplateIcon;
+  /* Code snippet to render in the template with syntax highlighting. */
+  query: string;
+  /* Code snippet to insert in the segment editor. If missing, `query` will be used. */
+  queryToInsert?: string;
+  /* List of customer standard metafields or custom metafields used in the template's query. */
+  dependencies?: {
+    standardMetafields?: CustomerStandardMetafieldDependency[];
+    customMetafields?: string[];
+  };
+  /* ISO 8601-encoded date and time string. A "New" badge will be rendered for recently introduced templates. */
+  createdOn?: string;
+  /* The category in which the template will be visible. The template will show in its respective category and aggregate sections. */
+  category: CustomerSegmentTemplateCategory;
+}
+
+/**
+ * Customer segment templates are used to give merchants a starting point to create segments.
+ */
+export const InternalCustomerSegmentTemplate = createRemoteComponent<
+  'InternalCustomerSegmentTemplate',
+  InternalCustomerSegmentTemplateProps
+>('InternalCustomerSegmentTemplate');

package/src/surfaces/admin/components/InternalCustomerSegmentTemplate/examples/InternalCustomerSegmentTemplate.example.ts

@@ -0,0 +1,45 @@
+import {
+  extension,
+  InternalCustomerSegmentTemplate,
+} from '@shopify/ui-extensions/admin';
+
+export default extension(
+  'admin.customers.segmentation-templates.render',
+  (root, {i18n, __enabledFeatures}) => {
+    const b2bEnabled =
+      __enabledFeatures.includes('b2bEnabled');
+    const companiesTemplate = root.createComponent(
+      InternalCustomerSegmentTemplate,
+      {
+        title: i18n.translate('companies.title'),
+        description: i18n.translate('companies.description'),
+        icon: 'buyButtonMajor',
+        query: 'companies IS NOT NULL',
+        dateAdded: new Date('2023-01-15').toISOString(),
+        category: 'reEngageCustomers',
+      },
+    );
+
+    const locationTemplate = root.createComponent(
+      InternalCustomerSegmentTemplate,
+      {
+        title: i18n.translate('location.title'),
+        description: [
+          i18n.translate('location.firstParagraph'),
+          i18n.translate('location.secondParagraph'),
+        ],
+        icon: 'locationMajor',
+        query: "customer_cities CONTAINS 'US-NY-NewYorkCity'",
+        category: 'location',
+      },
+    );
+
+    if (b2bEnabled) {
+      root.appendChild(companiesTemplate);
+    }
+
+    root.appendChild(locationTemplate);
+
+    root.mount();
+  },
+);

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

@@ -0,0 +1,76 @@
+import {createRemoteComponent} from '@remote-ui/core';
+
+export interface Location {
+  /**
+   * A unique identifier for the location.
+   */
+  id: string;
+
+  /**
+   * The name of the location.
+   */
+  name: string;
+}
+
+export interface LocationGroup {
+  /**
+   * An array of locations within the group.
+   */
+  locations: Location[];
+
+  /**
+   * The label for the location group.
+   */
+  label: string;
+
+  /**
+   * A unique identifier for the location group.
+   */
+  id: string;
+}
+
+export interface InternalLocationListProps {
+  /**
+   * An array of location groups.
+   */
+  locationGroups: LocationGroup[];
+
+  /**
+   * Callback when a location group is moved.
+   * It receives the old index and the new index as parameters.
+   */
+  onMoveGroup: (oldIndex: number, newIndex: number) => void;
+
+  /**
+   * Callback when a location group is renamed.
+   * It receives the id of the group and the new name as parameters.
+   */
+  onRenameGroup: (id: string, name: string) => void;
+
+  /**
+   * Callback when a location group is deleted.
+   * It receives the id of the group as a parameter.
+   */
+  onDeleteGroup: (id: string) => void;
+
+  /**
+   * Callback when a tag is moved from one group to another.
+   * It receives the id of the tag, the old group index, and the new group index as parameters.
+   */
+  onMoveTag: (
+    tagId: number,
+    oldGroupIndex: number,
+    newGroupIndex: number,
+  ) => void;
+
+  /**
+   * Callback when a new group is created.
+   * It receives the id of the new group as a parameter.
+   */
+  onCreateGroup: (id: string) => void;
+}
+
+export const InternalLocationList = createRemoteComponent<
+  'InternalLocationList',
+  InternalLocationListProps
+>('InternalLocationList');

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

@@ -2,7 +2,6 @@ import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
 
 const data: ReferenceEntityTemplateSchema = {
   name: 'Link',
-  featureFlag: 'admin_extensibility',
   description:
     'This is an interactive component that directs users to a specified URL. It even supports custom protocols.',
   requires: '',

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

@@ -1,6 +1,7 @@
 import {createRemoteComponent} from '@remote-ui/core';
+import {AccessibilityLabelProps} from '../shared';
 
-export interface LinkProps {
+export interface LinkProps extends AccessibilityLabelProps {
   /**
    * A unique identifier for the link.
    */
@@ -41,12 +42,6 @@ export interface LinkProps {
    */
   onPress?(): void;
 
-  /**
-   * A label used for users using assistive technologies. When set, any
-   * `children` supplied to this component will not be announced to screen reader users.
-   */
-  accessibilityLabel?: string;
-
   /**
    * Indicate the text language. Useful when the text is in a different language than the rest of the page.
    * It will allow assistive technologies such as screen readers to invoke the correct pronunciation.

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

@@ -0,0 +1,47 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'MoneyField',
+  description:
+    'This is the right component for letting users enter Money digits.',
+  requires: '',
+  thumbnail: 'moneyfield-thumbnail.png',
+  isVisualComponent: true,
+  type: '',
+  definitions: [
+    {
+      title: 'MoneyFieldProps',
+      description: '',
+      type: 'MoneyFieldProps',
+    },
+  ],
+  category: 'Components',
+  subCategory: 'Forms',
+  defaultExample: {
+    image: 'moneyfield-default.png',
+    codeblock: {
+      title: 'Simple MoneyField example',
+      tabs: [
+        {
+          title: 'React',
+          code: '../../../../../../ui-extensions-react/src/surfaces/admin/components/MoneyField/examples/basic-MoneyField.example.tsx',
+          language: 'tsx',
+        },
+        {
+          title: 'JS',
+          code: './examples/basic-MoneyField.example.ts',
+          language: 'js',
+        },
+      ],
+    },
+  },
+  related: [
+    {
+      type: 'component',
+      name: 'NumberField',
+      url: '/docs/api/admin-extensions/components/forms/numberfield',
+    },
+  ],
+};
+
+export default data;

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

@@ -0,0 +1,22 @@
+import {createRemoteComponent} from '@remote-ui/core';
+import type {
+  AutocompleteProps,
+  AnyAutocompleteField,
+  InputProps,
+  NumberConstraintsProps,
+  Money,
+} from '../shared';
+
+export interface MoneyFieldProps
+  extends InputProps<number | Money>,
+    NumberConstraintsProps,
+    AutocompleteProps<MoneyAutocompleteField> {}
+
+export type MoneyAutocompleteField = Extract<
+  AnyAutocompleteField,
+  'transaction-amount'
+>;
+
+export const MoneyField = createRemoteComponent<'MoneyField', MoneyFieldProps>(
+  'MoneyField',
+);

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

@@ -0,0 +1,3 @@
+# MoneyField
+
+Use a MoneyField to let the user enter a Money amount.

package/src/surfaces/admin/components/MoneyField/examples/basic-moneyfield.example.ts

@@ -0,0 +1,9 @@
+import {extend, MoneyFIeld} from '@shopify/ui-extensions/admin';
+
+extend('Playground', (root) => {
+  const urlField = root.createComponent(MoneyFIeld, {
+    label: 'Enter amount',
+  });
+
+  root.appendChild(urlField);
+});

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

@@ -2,7 +2,6 @@ import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
 
 const data: ReferenceEntityTemplateSchema = {
   name: 'NumberField',
-  featureFlag: 'admin_extensibility',
   description:
     'This component is specifically designed for numeric data entry.',
   requires: '',

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

@@ -5,10 +5,12 @@ import {
   AutocompleteFieldCreditCardAlias,
   AutocompleteFieldSecurityCodeAlias,
   InputProps,
+  NumberConstraintsProps,
 } from '../shared';
 
 export interface NumberFieldProps
   extends InputProps<number>,
+    NumberConstraintsProps,
     AutocompleteProps<NumberAutocompleteField> {
   /**
    * Sets the virtual keyboard.
@@ -16,34 +18,6 @@ export interface NumberFieldProps
    * @defaultValue 'decimal'
    */
   inputMode?: 'decimal' | 'numeric';
-
-  /**
-   * The highest decimal or integer to be accepted for the field.
-   * When used with `step` the value will round down to the max number.
-   * Note: a user will still be able to use the keyboard to input a number higher than
-   * the max. It is up to the developer to add appropriate validation.
-   */
-  max?: number;
-
-  /**
-   * The lowest decimal or integer to be accepted for the field.
-   * When used with `step` the value will round up to the min number.
-   * Note: a user will still be able to use the keyboard to input a number lower than
-   * the min. It is up to the developer to add appropriate validation.
-   *
-   * @defaultValue 0
-   */
-  min?: number;
-
-  /**
-   * 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
-   * via the buttons, the final value will always round to the `max` or `min`
-   * rather than the closest valid amount.
-   *
-   * @defaultValue 1
-   */
-  step?: number;
 }
 
 export type NumberAutocompleteField = Extract<

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

@@ -0,0 +1,48 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'Paragraph',
+  description:
+    'Use this to display a block of text similar to the <p> tag in HTML.',
+  requires: '',
+  thumbnail: 'paragraph-thumbnail.png',
+  isVisualComponent: true,
+  type: '',
+  definitions: [
+    {
+      title: 'ParagraphProps',
+      description: '',
+      type: 'ParagraphProps',
+    },
+  ],
+  category: 'Components',
+  subCategory: 'Titles and text',
+  defaultExample: {
+    image: 'paragraph-default.png',
+    codeblock: {
+      title: 'Simple Paragraph example',
+      tabs: [
+        {
+          title: 'React',
+          code: '../../../../../../ui-extensions-react/src/surfaces/admin/components/Paragraph/examples/basic-paragraph.example.tsx',
+          language: 'tsx',
+        },
+        {
+          title: 'JS',
+          code: './examples/basic-paragraph.example.ts',
+          language: 'js',
+        },
+      ],
+    },
+  },
+
+  related: [
+    {
+      type: 'component',
+      name: 'Heading',
+      url: '/docs/api/admin-extensions/components/titles-and-text/heading',
+    },
+  ],
+};
+
+export default data;

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

@@ -0,0 +1,10 @@
+import {createRemoteComponent} from '@remote-ui/core';
+import type {BaseTypographyProps, GlobalProps} from '../shared';
+
+export interface ParagraphProps extends BaseTypographyProps, GlobalProps {
+  children?: any;
+}
+
+export const Paragraph = createRemoteComponent<'Paragraph', ParagraphProps>(
+  'Paragraph',
+);

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

@@ -0,0 +1,7 @@
+# Paragraph
+
+Use this to display a block of text similar to the <p> tag in HTML.
+
+## Expected HTML in Web host
+
+`<p>Hello, World!</p>`

package/src/surfaces/admin/components/Paragraph/examples/basic-paragraph.example.ts

@@ -0,0 +1,10 @@
+import {extend, Paragraph, BlockStack} from '@shopify/ui-extensions/admin';
+
+extend('Playground', (root) => {
+  const paragraph = root.createComponent(BlockStack, {inlineAlignment: 'center', gap: true}, [
+    root.createComponent(Paragraph, {fontWeight: 'bold'}, 'Name:'),
+    root.createComponent(Paragraph, {}, 'Jane Doe'),
+  ]);
+
+  root.appendChild(paragraph);
+});

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

@@ -2,7 +2,6 @@ import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
 
 const data: ReferenceEntityTemplateSchema = {
   name: 'PasswordField',
-  featureFlag: 'admin_extensibility',
   description:
     'This component is for secure input, it obfuscates any text that users enter.',
   requires: '',

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

@@ -2,7 +2,6 @@ import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
 
 const data: ReferenceEntityTemplateSchema = {
   name: 'Pressable',
-  featureFlag: 'admin_extensibility',
   description:
     'Use this component when you need to capture click or press events on its child elements without adding any additional visual styling. It subtly enhances user interaction by changing the cursor when hovering over the child elements, providing a clear indication of interactivity.',
   requires: '',