@shopify/ui-extensions 0.0.0-internal-20230622171951

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

@@ -0,0 +1,68 @@
+import {createRemoteComponent} from '@remote-ui/core';
+
+import {IconProps} from '../Icon/Icon';
+
+type RequiredTitleOrIcon =
+  | {
+      /** Button label text */
+      title: string;
+      icon?: IconProps;
+    }
+  | {
+      /** Button label text */
+      title?: string;
+      icon: IconProps;
+    };
+
+export interface BaseButtonProps {
+  /**
+   * The type of button that will be rendered.
+   *
+   * `primary`: button used for main actions or green-path. Ex: Continue to next step, Discount field
+   * `secondary`: button used for secondary actions not blocking user progress. Ex: Download Shop app
+   * `plain`: Renders a button that visually looks like a Link
+   *  @default 'secondary'
+   */
+  kind?: 'primary' | 'secondary' | 'plain';
+  /**
+   *  Specifies the color of the Button. The button will keep the style of the chosen `kind`,
+   *  but replace its color according to the appearance.
+   *
+   * `monochrome`: button will inherit the color of its parent
+   * `critical`: button will take inherit the color of the Critical color group (in Checkout)
+   *  		 and map to 'destructive' (in Admin/Polaris). Typically used for destructive actions.
+   *
+   */
+  appearance?: 'critical';
+  /** Changes the size of the button
+   * @default 'base'
+   */
+  size?: 'base' | 'large';
+  /**
+   * Whether the button should fill all available inline space.
+   * */
+  inlineSize?: 'fill';
+  /**
+   * Replaces content with a loading indicator
+   */
+  loading?: boolean;
+  /**
+   * A label that will be announced to buyers using assistive technologies
+   */
+  accessibilityLabel?: string;
+  /**
+   * Disables the button, disallowing any interaction
+   */
+  disabled?: boolean;
+  /**
+   * Callback when pressed
+   */
+  onPress?(): void;
+}
+
+export type ButtonProps = RequiredTitleOrIcon & BaseButtonProps;
+
+/**
+ * Buttons are used primarily for actions, such as “Add”, “Close”, “Cancel”, or “Save”.
+ */
+export const Button = createRemoteComponent<'Button', ButtonProps>('Button');

package/src/surfaces/admin/components/Button/content/guidelines.md

@@ -0,0 +1,14 @@
+## Guidelines
+
+- 📱 Buttons will wrap their content if placed inside a `Stack` component, otherwise they will expand to the width of the container
+- 🖥 Buttons wrap their content, regardless of the container they are placed in
+
+| ✅ Do                                              | 🛑 Don't                                     |
+| -------------------------------------------------- | -------------------------------------------- | --- |
+| 📱 Align buttons vertically                        | 📱Buttons should not be stacked horizontally |
+| Use short, succinct titles that describe an action |                                              |
+| Use an icon to supplement the title of the button  |                                              |
+| Use only a single primary Button per section       |                                              |
+| Primary buttons should be before secondary buttons |                                              |     |
+
+For more guidelines, refer to Polaris' [Button best practices](https://polaris.shopify.com/components/actions/button#section-best-practices).

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

@@ -0,0 +1,17 @@
+import {extension, Button} from '@shopify/ui-extensions/admin';
+
+export default extension('Playground', (root) => {
+  const button = root.createComponent(Button, {
+    title: 'Settings',
+    kind: 'primary',
+    appearance: 'critical',
+    size: 'large',
+    inlineSize: 'fill',
+    accessibilityLabel: 'open settings',
+    disabled: false,
+    onPress: () => console.log('Pressed'),
+  });
+
+  root.appendChild(button);
+  root.mount();
+});

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

@@ -0,0 +1,28 @@
+import {createRemoteComponent} from '@remote-ui/core';
+
+import {DestructableAction, DisableableAction} from '../shared';
+
+export interface CardProps {
+  /** Title content for the card */
+  title?: string;
+
+  /** Automatically wrap each child component in a `Card.Section` */
+  sectioned?: boolean;
+
+  /** Primary action for the card footer */
+  primaryFooterAction?: DestructableAction;
+
+  /** Secondary actions for the card footer */
+  secondaryFooterActions?: DestructableAction[];
+
+  /** Card header action */
+  actions?: DisableableAction[];
+}
+
+/**
+ * Cards are used to group similar concepts and tasks together to make Shopify easier for merchants to scan, read, and get things done.
+ *
+ * The action API should be used to create actionable components for the card.
+ * Cards should be contained, independent, and individual.
+ */
+export const Card = createRemoteComponent<'Card', CardProps>('Card');

package/src/surfaces/admin/components/Card/content/guidelines.md

@@ -0,0 +1,9 @@
+## Guidelines
+
+- 📱 Do not nest Cards within another component. This will result in unintended behavior, and will not render correctly
+
+| ✅ Do                                                       | 🛑 Don't                       |
+| ----------------------------------------------------------- | ------------------------------ |
+| Cards should be at the top level of the component hierarchy | Use too many secondary actions |
+
+For more guidelines, refer to Polaris' [Card best practices](https://polaris.shopify.com/components/structure/card#section-best-practices).

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

@@ -0,0 +1,10 @@
+import {extension, Card} from '@shopify/ui-extensions/admin';
+
+export default extension('Playground', (root) => {
+  const card = root.createComponent(Card, {});
+
+  card.appendChild('This is the best extension.');
+  root.appendChild(card);
+
+  root.mount();
+});

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

@@ -0,0 +1,13 @@
+import {createRemoteComponent} from '@remote-ui/core';
+
+export interface CardSectionProps {
+  title?: string;
+}
+
+/**
+ * CardSections are used to group similar concepts within a Card. CardSections add dividers, which visually separate regions within cards.
+ */
+export const CardSection = createRemoteComponent<
+  'CardSection',
+  CardSectionProps
+>('CardSection');

package/src/surfaces/admin/components/CardSection/content/guidelines.md

@@ -0,0 +1,5 @@
+## Guidelines
+
+| ✅ Do                                           | 🛑 Don't                        |
+| ----------------------------------------------- | ------------------------------- |
+| Use CardSection to split up content within Card | Use CardSection outside of Card |

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

@@ -0,0 +1,20 @@
+import {extension, Card, CardSection} from '@shopify/ui-extensions/admin';
+
+export default extension('Playground', (root) => {
+  const card = root.createComponent(Card, {});
+  root.appendChild(card);
+
+  const cardSection = root.createComponent(CardSection, {
+    title: 'Sectional',
+  });
+  cardSection.appendChild('This is the best section.');
+  card.appendChild(cardSection);
+
+  const cardSection2 = root.createComponent(CardSection, {
+    title: 'Loveseat',
+  });
+  cardSection.appendChild('No, this is the best section.');
+  card.appendChild(cardSection2);
+
+  root.mount();
+});

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

@@ -0,0 +1,25 @@
+import {createRemoteComponent} from '@remote-ui/core';
+
+export interface CheckboxProps {
+  /** Label for the checkbox. */
+  label?: string;
+
+  /** Checkbox is selected. */
+  checked?: boolean;
+
+  /**
+   * Alias for `checked`, to support iterating over multiple types of form fields.
+   * If both `checked` and `value` are used, `checked` is the source of truth.
+   */
+  value?: boolean;
+
+  /** Callback when checkbox is toggled. */
+  onChange?(value: boolean): void | Promise<void>;
+}
+
+/**
+ * Checkboxes are most commonly used to give merchants a way to make a range of selections (zero, one, or multiple).
+ */
+export const Checkbox = createRemoteComponent<'Checkbox', CheckboxProps>(
+  'Checkbox',
+);

package/src/surfaces/admin/components/Checkbox/content/guidelines.md

@@ -0,0 +1,8 @@
+## Guidelines
+
+| ✅ Do                                                  | 🛑 Don't                      |
+| ------------------------------------------------------ | ----------------------------- |
+| Use Checkboxes to give merchants a multi select choice | Horizontally stack Checkboxes |
+| Vertically align Checkboxes                            |                               |
+
+For more guidelines, refer to Polaris' [Checkbox best practices](https://polaris.shopify.com/components/forms/checkbox#section-best-practices).

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

@@ -0,0 +1,13 @@
+import {extension, ExtensionPoint, Checkbox} from '@shopify/ui-extensions/admin';
+
+export default extension('Playground', (root) => {
+  const checkbox = root.createComponent(Checkbox, {
+    label: 'Opt in to something cool',
+    checked: true,
+    onChange: () => console.log('Checked'),
+  });
+
+  root.appendChild(checkbox);
+
+  root.mount();
+});

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

@@ -0,0 +1,66 @@
+import {createRemoteComponent} from '@remote-ui/core';
+
+type Source =
+  | 'categoriesMajor'
+  | 'firstVisitMajor'
+  | 'heartMajor'
+  | 'marketingMajor'
+  | 'checkoutMajor'
+  | 'ordersMajor'
+  | 'locationMajor'
+  | 'emailNewsletterMajor'
+  | 'firstOrderMajor'
+  | 'billingStatementDollarMajor'
+  | 'diamondAlertMajor'
+  | 'abandonedCartMajor'
+  | 'calendarMajor'
+  | 'productsMajor'
+  | 'globeMajor'
+  | 'flagMajor'
+  | 'uploadMajor'
+  | 'buyButtonMajor'
+  | 'followUpEmailMajor'
+  | 'confettiMajor';
+
+type TemplateCategory =
+  | '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 CustomerSegmentationTemplateProps {
+  /* Localized title of the template. */
+  title: string;
+  /* Localized description(s) of the template. */
+  description: string | string[];
+  /* Icon identifier for the template. This property is ignored for non-1P Segmentation templates as we fallback to the app icon */
+  icon?: Source;
+  /* ShopifyQL code snippet to render in the template with syntax highlighting. */
+  templateQuery: string;
+  /* ShopifyQL code snippet to insert in the segment editor. If missing, `templateQuery` will be used. */
+  templateQueryToInsert?: string;
+  /* List of customer standard metafield used in the template's query. */
+  standardMetafieldDependencies?: CustomerStandardMetafieldDependency[];
+  /* ISO 8601-encoded date and time string. A "New" badge will be rendered for recently introduced templates. */
+  dateAdded?: string;
+  /* The category in which the template will be visible.
+     When provided, the template will show in its respective category and aggregate sections.
+     When missing, the template will show in the aggregate sections only */
+  category?: TemplateCategory;
+}
+
+/**
+ * Customer segmentation templates are used to give merchants a starting point to create segments.
+ */
+export const CustomerSegmentationTemplate = createRemoteComponent<
+  'CustomerSegmentationTemplate',
+  CustomerSegmentationTemplateProps
+>('CustomerSegmentationTemplate');

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

@@ -0,0 +1,37 @@
+import {
+  extension,
+  CustomerSegmentationTemplate,
+} from '@shopify/ui-extensions/admin';
+
+export default extension(
+  'admin.customers.segmentation-templates.render',
+  (root, {i18n, __enabledFeatures}) => {
+    const productsPurchasedOnTagsEnabled = __enabledFeatures.includes('productsPurchasedByTags');
+    const productTemplate = root.createComponent(CustomerSegmentationTemplate, {
+      title: i18n.translate('product.title'),
+      description: i18n.translate('product.description'),
+      icon: 'productsMajor',
+      templateQuery: productsPurchasedOnTagsEnabled
+      ? 'products_purchased(tag: (product_tag)) = true'
+      : 'products_purchased(id: (product_id)) = true',
+      templateQueryToInsert: productsPurchasedOnTagsEnabled
+      ? 'products_purchased(tag:'
+      : 'products_purchased(id:',
+      dateAdded: new Date('2023-01-15').toISOString(),
+      category: 'reEngageCustomers'
+    });
+
+    const locationTemplate = root.createComponent(CustomerSegmentationTemplate, {
+      title: i18n.translate('location.title'),
+      description: [i18n.translate('location.firstParagraph'), i18n.translate('location.secondParagraph')],
+      icon: 'locationMajor',
+      templateQuery: "customer_cities CONTAINS 'US-NY-NewYorkCity'",
+      category: 'location'
+    });
+
+    root.appendChild(productTemplate);
+    root.appendChild(locationTemplate);
+
+    root.mount();
+  },
+);

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

@@ -0,0 +1,25 @@
+import {createRemoteComponent} from '@remote-ui/core';
+
+type Level = 1 | 2 | 3 | 4 | 5 | 6;
+
+export interface HeadingProps {
+  /**
+   * Unique identifier. Typically used to make the heading a target
+   * that another component can refer to in order to provide an alternative
+   * accessibility label.
+   */
+  id?: string;
+
+  /**
+   * The visual level of the heading.
+   * @default 2
+   */
+  level?: Level;
+}
+
+/**
+ * Headings are used as the titles of each major section of an extension.
+ */
+export const Heading = createRemoteComponent<'Heading', HeadingProps>(
+  'Heading',
+);

package/src/surfaces/admin/components/Heading/content/guidelines.md

@@ -0,0 +1,11 @@
+## Guidelines
+
+- 📱 Headings should clearly describe the section of interface they refer to
+- 📱 Use Headings to highlight the most important concept or piece of information merchants need to know
+
+| ✅ Do                                                           | 🛑 Don't                           |
+| --------------------------------------------------------------- | ---------------------------------- |
+| Use headings to support the hierarchy and structure of the page | Nest too many Headings in one area |
+| Place Headings at the top of a page or section they refer to    |                                    |
+
+For more guidelines, refer to Polaris' [Heading best practices](https://polaris.shopify.com/components/titles-and-text/heading#section-best-practices).

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

@@ -0,0 +1,14 @@
+import {extension, Heading} from '@shopify/ui-extensions/admin';
+
+export default extension('Playground', (root) => {
+  const heading = root.createComponent(Heading, {
+    id: 'profile_heading',
+    level: 3,
+  });
+
+  const headingText = root.createText('This is a Title');
+  heading.appendChild(headingText);
+  root.appendChild(heading);
+
+  root.mount();
+});

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

@@ -0,0 +1,21 @@
+import {createRemoteComponent} from '@remote-ui/core';
+
+type Source =
+  | 'cancelSmallMinor'
+  | 'searchMinor'
+  | 'starHollow'
+  | 'starFilled'
+  | 'sortMinor';
+
+export interface IconProps {
+  /** Pre-defined glyph content to display. */
+  source: Source;
+
+  /** Text describing the icon, to be read to screenreaders. */
+  accessibilityLabel?: string;
+}
+
+/**
+ * Icons are small visual indicators from a set of pre-defined glyphs.
+ */
+export const Icon = createRemoteComponent<'Icon', IconProps>('Icon');

package/src/surfaces/admin/components/Icon/content/guidelines.md

@@ -0,0 +1,8 @@
+## Guidelines
+
+| ✅ Do                                                                                                                           | 🛑 Don't                                        |
+| ------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
+| Use Icons to provide visual indicators to your actions, such as sorting and searching                                           | Use the same accessibility label for every Icon |
+| Use a unique accessibility label that describes the Icon, so that the merchants device’s screen reader can announce the content |                                                 |
+
+For more guidelines, refer to Polaris' [Icon related guidelines](https://polaris.shopify.com/components/images-and-icons/icon#section-related-guidelines).

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

@@ -0,0 +1,12 @@
+import {extension, Icon} from '@shopify/ui-extensions/admin';
+
+export default extension('Playground', (root) => {
+  const icon = root.createComponent(Icon, {
+    source: 'cancelSmallMinor',
+  });
+
+  icon.appendChild('This is the best extension.');
+  root.appendChild(icon);
+
+  root.mount();
+});

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

@@ -0,0 +1,34 @@
+import {createRemoteComponent} from '@remote-ui/core';
+
+import type {Spacing} from '../shared';
+
+export interface InlineStackProps {
+  /**
+   * Specifies the block alignment. This affects the vertical flow of elements.
+   * @defaultValue `leading`
+   */
+  blockAlignment?: 'leading' | 'center' | 'trailing' | 'baseline';
+
+  /**
+   * Specifies the inline alignment. This affects the horizontal flow of elements.
+   * @defaultValue `leading`
+   */
+  inlineAlignment?: 'leading' | 'center' | 'trailing';
+
+  /**
+   * Adjust spacing between children.
+   * @defaultValue 'base'
+   **/
+  spacing?: Spacing;
+}
+
+/**
+ * Use to lay out a horizontal row of components.
+ *
+ * A stack is made of flexible items that wrap each of the stack’s children. Options provide control of the alignment and spacing of the items in the stack.
+ * Use `StackItem` to group multiple elements inside a `InlineStack` together.
+ */
+export const InlineStack = createRemoteComponent<
+  'InlineStack',
+  InlineStackProps
+>('InlineStack');

package/src/surfaces/admin/components/InlineStack/content/guidelines.md

@@ -0,0 +1,10 @@
+## Guidelines
+
+- 📱 All children of `InlineStack` are placed in a single view object, which makes recycling the views expensive and results in poorer performance when scrolling. Consider keeping your Stacks simple.
+- By default, `InlineStack` alignment is `'leading’`.
+
+| ✅ Do                                                                         | 🛑 Don't                              |
+| ----------------------------------------------------------------------------- | ------------------------------------- |
+| 📱 Keep Inline Stacks shallow. Complex hierarchies have performance penalties | 📱 Use complex and deep Stack layouts |
+
+For more guidelines, refer to Polaris' [Stack best practices](https://polaris.shopify.com/components/structure/stack#section-best-practices).

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

@@ -0,0 +1,16 @@
+import {extension, InlineStack, Text} from '@shopify/ui-extensions/admin';
+
+export default extension('Playground', (root) => {
+  const inlineStack = root.createComponent(InlineStack, {
+    inlineAlignment: 'center',
+    spacing: 'loose',
+  }, [
+    root.createComponent(Text, undefined, 'Items to stack'),
+    root.createComponent(Text, undefined, 'Items to stack'),
+    root.createComponent(Text, undefined, 'Items to stack'),
+  ]);
+
+  root.appendChild(inlineStack);
+
+  root.mount();
+});

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

@@ -0,0 +1,23 @@
+import {createRemoteComponent} from '@remote-ui/core';
+
+export interface LinkProps {
+  /**
+   * Callback when the link is pressed.
+   */
+  onPress?: () => void;
+
+  /**
+   * Open the link in a new tab on desktop, or in the device browser on mobile.
+   */
+  external?: boolean;
+
+  /**
+   * A relative path or absolute URL to link to.
+   */
+  url?: string;
+}
+
+/**
+ * Links take users to another place, and usually appear within or directly following a sentence.
+ */
+export const Link = createRemoteComponent<'Link', LinkProps>('Link');

package/src/surfaces/admin/components/Link/content/guidelines.md

@@ -0,0 +1,10 @@
+## Guidelines
+
+- 📱 Only nest Text within Link. Other components will be ignored. Nested Text components can be used to render the content of the Link
+
+| ✅ Do                                                                     | 🛑 Don't                                              |
+| ------------------------------------------------------------------------- | ----------------------------------------------------- |
+| 📱 Use `external` to launch URLs with the device browser                  | Inject Javascript into the URL. This will be blocked. |
+| 🖥 Use `external` to launch URLs in a new browser tab. Use HTTPS for URLs. |                                                       |
+
+For more guidelines, refer to Polaris' [Link best practices](https://polaris.shopify.com/components/navigation/link#section-best-practices).

package/src/surfaces/admin/components/Link/examples/AbsoluteLink.example.ts

@@ -0,0 +1,13 @@
+import {extension, Link} from '@shopify/ui-extensions/admin';
+
+export default extension('Playground', (root) => {
+  const link = root.createComponent(Link, {
+    url: 'https://shopify.com',
+    external: true,
+  });
+  link.appendChild('The best product ever!');
+
+  root.appendChild(link);
+
+  root.mount();
+});

package/src/surfaces/admin/components/Link/examples/LogLink.example.ts

@@ -0,0 +1,12 @@
+import {extension, Link} from '@shopify/ui-extensions/admin';
+
+export default extension('Playground', (root) => {
+  const logLink = root.createComponent(Link, {
+    onPress: () => console.log('I was pressed'),
+  });
+  logLink.appendChild('I don’t do much.');
+
+  root.appendChild(logLink);
+
+  root.mount();
+});

package/src/surfaces/admin/components/Link/examples/RelativeLink.example.ts

@@ -0,0 +1,12 @@
+import {extension, Link} from '@shopify/ui-extensions/admin';
+
+export default extension('Playground', (root) => {
+  const productLink = root.createComponent(Link, {
+    url: '/admin/products/12345',
+  });
+  productLink.appendChild('View product');
+
+  root.appendChild(productLink);
+
+  root.mount();
+});

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

@@ -0,0 +1,33 @@
+import {createRemoteComponent} from '@remote-ui/core';
+
+import {DestructableAction} from '../shared';
+
+export interface ModalProps {
+  /**
+   * Whether the modal is open.
+   */
+  open: boolean;
+  /**
+   * Title content for the modal, when rendered.
+   */
+  title: string;
+  /**
+   * Modal's primary action, ie 'Save' or 'Accept'.
+   */
+  primaryAction?: DestructableAction;
+  /**
+   * Modal's secondary action(s), ie 'Cancel'.
+   */
+  secondaryActions?: DestructableAction[];
+  /**
+   * Callback when the modal is closed.
+   */
+  onClose: () => void;
+}
+
+/**
+ * Modals are overlays that prevent merchants from interacting with the rest of the application until a specific action is taken.
+ *
+ * Modals are disruptive by design, requiring merchants to take an action before they can continue, so use them thoughtfully and sparingly.
+ */
+export const Modal = createRemoteComponent<'Modal', ModalProps>('Modal');

package/src/surfaces/admin/components/Modal/content/guidelines.md

@@ -0,0 +1,8 @@
+## Guidelines
+
+| ✅ Do                                                         | 🛑 Don't                                   |
+| ------------------------------------------------------------- | ------------------------------------------ |
+| Use modals thoughtfully and sparingly                         | Avoid overly complex or multi-step content |
+| Use modals with a small and simple set of actions to complete |                                            |
+
+For more guidelines, refer to Polaris' [Modal best practices](https://polaris.shopify.com/components/overlays/modal#section-best-practices).

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

@@ -0,0 +1,14 @@
+import {extension, Modal} from '@shopify/ui-extensions/admin';
+
+export default extension('Playground', (root) => {
+  const modal = root.createComponent(Modal, {
+    title: 'The best modal',
+    onClose: () => console.log('modal closed!'),
+    open: true,
+  });
+
+  modal.appendChild('This is the content of the modal.');
+  root.appendChild(modal);
+
+  root.mount();
+});