@shopify/ui-extensions 2023.7.2 → 2024.1.0

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

@@ -0,0 +1,48 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'ChoiceList',
+  description:
+    'Use this component if you need to group together a related list of interactive choices as radio buttons or checkboxes.',
+  requires: '',
+  thumbnail: 'choicelist-thumbnail.png',
+  isVisualComponent: true,
+  type: '',
+  definitions: [
+    {
+      title: 'ChoiceListProps',
+      description: '',
+      type: 'ChoiceListProps',
+    },
+  ],
+  category: 'Components',
+  subCategory: 'Forms',
+  defaultExample: {
+    image: 'choicelist-default.png',
+    codeblock: {
+      title: 'Simple ChoiceList example',
+      tabs: [
+        {
+          title: 'React',
+          code: '../../../../../../ui-extensions-react/src/surfaces/admin/components/ChoiceList/examples/basic-ChoiceList.example.tsx',
+          language: 'tsx',
+        },
+        {
+          title: 'JS',
+          code: './examples/basic-ChoiceList.example.ts',
+          language: 'js',
+        },
+      ],
+    },
+  },
+
+  related: [
+    {
+      type: 'component',
+      name: 'Select',
+      url: '/docs/api/admin-extensions/components/forms/select',
+    },
+  ],
+};
+
+export default data;

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

@@ -0,0 +1,36 @@
+import {createRemoteComponent} from '@remote-ui/core';
+import {AccessibilityLabelProps, InputProps} from '../shared';
+
+export interface ChoiceProps
+  extends AccessibilityLabelProps,
+    Pick<
+      InputProps<string>,
+      'disabled' | 'label' | 'id' | 'readOnly' | 'error'
+    > {
+  /**
+   * Whether the choice is checked or not
+   */
+  checked?: boolean;
+}
+
+export interface ChoiceListProps
+  extends Pick<
+    InputProps<string | string[]>,
+    | 'value'
+    | 'name'
+    | 'onChange'
+    | 'disabled'
+    | 'error'
+    | 'readOnly'
+    | 'defaultValue'
+  > {
+  choices?: ChoiceProps[];
+  /**
+   * Whether to allow selection of multiple choices
+   */
+  multiple?: boolean;
+}
+
+export const ChoiceList = createRemoteComponent<'ChoiceList', ChoiceListProps>(
+  'ChoiceList',
+);

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

@@ -0,0 +1,23 @@
+import {
+  extension,
+  ChoiceList,
+} from '@shopify/ui-extensions/admin';
+
+export default extension(
+  'Playground',
+  (root) => {
+    const blockStack = root.createComponent(
+      ChoiceList,
+      {
+        name: 'Company name',
+        choices: [
+            {label: 'Hidden', id: '1'},
+            {label: 'Optional', id: '2'},
+            {label: 'Required', id: '3'},
+        ]
+      },
+    );
+
+    root.appendChild(blockStack);
+  },
+);

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

@@ -0,0 +1,47 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'ColorPicker',
+  description: 'Use this component if you need to select a color.',
+  requires: '',
+  thumbnail: 'colorpicker-thumbnail.png',
+  isVisualComponent: true,
+  type: '',
+  definitions: [
+    {
+      title: 'ColorPickerProps',
+      description: '',
+      type: 'ColorPickerProps',
+    },
+  ],
+  category: 'Components',
+  subCategory: 'Forms',
+  defaultExample: {
+    image: 'colorpicker-default.png',
+    codeblock: {
+      title: 'Simple ColorPicker example',
+      tabs: [
+        {
+          title: 'React',
+          code: '../../../../../../ui-extensions-react/src/surfaces/admin/components/ColorPicker/examples/basic-ColorPicker.example.tsx',
+          language: 'tsx',
+        },
+        {
+          title: 'JS',
+          code: './examples/basic-ColorPicker.example.ts',
+          language: 'js',
+        },
+      ],
+    },
+  },
+
+  related: [
+    {
+      type: 'component',
+      name: 'Select',
+      url: '/docs/api/admin-extensions/components/forms/select',
+    },
+  ],
+};
+
+export default data;

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

@@ -0,0 +1,43 @@
+import {createRemoteComponent} from '@remote-ui/core';
+
+export interface ColorPickerProps {
+  /** ID for the element. */
+  id?: string;
+
+  /**
+   * Allow user to select an alpha value.
+   * @default false
+   */
+  allowAlpha?: boolean;
+
+  /**
+   * The `onChange` handler will emit the value in hex.
+   * If the `allowAlpha` prop is `true`, `onChange` will emit an 8-value hex (#RRGGBBAA).
+   * If the `allowAlpha` prop is `false`, `onChange` will emit a 6-value hex (#RRGGBB).
+   */
+  onChange?(value: string): void;
+
+  /**
+   * The currently selected color.
+   *
+   * Supported formats include:
+   * - RGB @see https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/rgb
+   * - RGBA @see https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/rgb
+   * - Hex (3-value, 4-value, 6-value, 8-value) @see https://developer.mozilla.org/en-US/docs/Web/CSS/hex-color
+   *
+   * For RGB and RGBA, both the legacy syntax (comma-separated) and modern syntax (space-separate) are supported.
+   * @see https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/rgb
+   *
+   * If the value is invalid, the component will select rgb(0, 0, 0).
+   *
+   * The `onChange` handler will emit the value in hex.
+   * If the `allowAlpha` prop is `true`, `onChange` will emit an 8-value hex (#RRGGBBAA).
+   * If the `allowAlpha` prop is `false`, `onChange` will emit a 6-value hex (#RRGGBB).
+   */
+  value?: string;
+}
+
+export const ColorPicker = createRemoteComponent<
+  'ColorPicker',
+  ColorPickerProps
+>('ColorPicker');

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

@@ -0,0 +1,19 @@
+import {
+  extension,
+  ColorPicker,
+} from '@shopify/ui-extensions/admin';
+
+export default extension(
+  'Playground',
+  (root) => {
+    const blockStack = root.createComponent(
+      ColorPicker,
+      {
+        value: "rgba(255 0 0 / 0.5)",
+        label: ""
+      },
+    );
+
+    root.appendChild(blockStack);
+  },
+);

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

@@ -0,0 +1,42 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'CustomerSegmentTemplate',
+  description:
+    'CustomerSegmentTemplate is used to configure a template rendered in the **Customers** section of the Shopify admin. Templates can be applied in the [customer segment editor](https://help.shopify.com/en/manual/customers/customer-segmentation/customer-segments) and used to create segments.',
+  requires:
+    'use of the [admin.customers.segmentation-templates.render](/docs/api/admin-extensions/api/extension-targets#extensiontargets-propertydetail-admincustomerssegmentationtemplatesrender) target.',
+  isVisualComponent: true,
+  thumbnail: 'customersegmenttemplate-thumbnail.png',
+  type: '',
+  definitions: [
+    {
+      title: 'CustomerSegmentTemplateProps',
+      description: '',
+      type: 'CustomerSegmentTemplateProps',
+    },
+  ],
+  category: 'Components',
+  subCategory: 'Other',
+  defaultExample: {
+    image: 'customersegmenttemplate-default',
+    codeblock: {
+      title: 'Simple CustomerSegmentTemplate implementation',
+      tabs: [
+        {
+          title: 'React',
+          code: './examples/CustomerSegmentTemplate.example.tsx',
+          language: 'tsx',
+        },
+        {
+          title: 'JS',
+          code: './examples/CustomerSegmentTemplate.example.ts',
+          language: 'js',
+        },
+      ],
+    },
+  },
+  related: [],
+};
+
+export default data;

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

@@ -0,0 +1,45 @@
+import {createRemoteComponent} from '@remote-ui/core';
+
+/**
+ * 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 CustomerSegmentTemplateProps {
+  /**
+   * The localized title of the template.
+   */
+  title: string;
+  /**
+   * The localized description of the template. An array can be used for multiple paragraphs.
+   */
+  description: string | string[];
+  /**
+   * The code snippet to render in the template with syntax highlighting. The `query` is not validated in the template.
+   */
+  query: string;
+  /**
+   * The code snippet to insert in the segment editor. If missing, `query` will be used. The `queryToInsert` is not validated in the template.
+   */
+  queryToInsert?: string;
+  /**
+   * The 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 templates introduced in the last month.
+   */
+  createdOn?: string;
+}
+
+/**
+ * Customer segmentation templates are used to give merchants a starting point to create segments.
+ */
+export const CustomerSegmentTemplate = createRemoteComponent<
+  'CustomerSegmentTemplate',
+  CustomerSegmentTemplateProps
+>('CustomerSegmentTemplate');

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

@@ -0,0 +1,17 @@
+import {extension, CustomerSegmentTemplate} from '@shopify/ui-extensions/admin';
+
+export default extension(
+  'admin.customers.segmentation-templates.render',
+  (root, {i18n}) => {
+    const template = root.createComponent(CustomerSegmentTemplate, {
+      title: i18n.translate('template.title'),
+      description: i18n.translate('template.description'),
+      query: "number_of_orders > 0'",
+      createdOn: new Date('2023-01-15').toISOString(),
+    });
+
+    root.appendChild(template);
+
+    root.mount();
+  },
+);

package/src/surfaces/admin/components/CustomerSegmentTemplate/examples/CustomerSegmentTemplate.example.tsx

@@ -0,0 +1,15 @@
+import React from 'react';
+import {reactExtension, CustomerSegmentTemplate} from '@shopify/ui-extensions/admin';
+
+function App() {
+  return (
+    <CustomerSegmentTemplate
+        title="My Customer Segment Template"
+        description="Description of the segment"
+        query="number_of_orders > 0"
+        createdOn={new Date('2023-01-15').toISOString()}
+    />
+  );
+}
+
+export default reactExtension('Playground', () => <App />);

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

@@ -0,0 +1,83 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'DateField',
+  description:
+    'This is a form field that lets merchants select a date. It uses the DatePicker component to let merchants to pick the date.',
+  requires: '',
+  thumbnail: 'datefield-thumbnail.png',
+  isVisualComponent: true,
+  type: '',
+  definitions: [
+    {
+      title: 'DatePickerProps',
+      description: '',
+      type: 'DatePickerProps',
+    },
+  ],
+  category: 'Components',
+  subCategory: 'Forms',
+  defaultExample: {
+    image: 'datefield-default.png',
+    codeblock: {
+      title: 'Add a single-date DateField',
+      tabs: [
+        {
+          title: 'React',
+          code: '../../../../../../ui-extensions-react/src/surfaces/admin/components/DateField/examples/basic-datefield.example.tsx',
+          language: 'tsx',
+        },
+        {
+          title: 'JS',
+          code: './examples/basic-datefield.example.ts',
+          language: 'js',
+        },
+      ],
+    },
+  },
+  examples: {
+    description: '',
+    examples: [
+      {
+        description: 'Use this when merchants need to select multiple dates.',
+        codeblock: {
+          title: 'Add a multi-date DateField',
+          tabs: [
+            {
+              title: 'React',
+              code: '../../../../../../ui-extensions-react/src/surfaces/admin/components/DateField/examples/multiple-datefield.example.tsx',
+              language: 'tsx',
+            },
+            {
+              title: 'JS',
+              code: './examples/multiple-datefield.example.ts',
+              language: 'js',
+            },
+          ],
+        },
+      },
+      {
+        description: 'Use this when merchants need to select a range of dates.',
+        codeblock: {
+          title: 'Add a range DateField',
+          tabs: [
+            {
+              title: 'React',
+              code: '../../../../../../ui-extensions-react/src/surfaces/admin/components/DateField/examples/range-datefield.example.tsx',
+              language: 'tsx',
+            },
+            {
+              title: 'JS',
+              code: './examples/range-datefield.example.ts',
+              language: 'js',
+            },
+          ],
+        },
+      },
+    ],
+  },
+
+  related: [],
+};
+
+export default data;

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

@@ -0,0 +1,26 @@
+import {createRemoteComponent} from '@remote-ui/core';
+import type {DatePickerProps} from '../DatePicker/DatePicker';
+import type {TextFieldProps} from '../TextField/TextField';
+
+export interface DateFieldProps
+  extends Pick<
+      TextFieldProps,
+      | 'label'
+      | 'name'
+      | 'id'
+      | 'readOnly'
+      | 'onFocus'
+      | 'onInput'
+      | 'onBlur'
+      | 'onChange'
+      | 'error'
+      | 'value'
+    >,
+    Pick<
+      DatePickerProps<string>,
+      'yearMonth' | 'defaultYearMonth' | 'disabled' | 'onYearMonthChange'
+    > {}
+
+export const DateField = createRemoteComponent<'DateField', DateFieldProps>(
+  'DateField',
+);

package/src/surfaces/admin/components/DateField/examples/basic-datefield.example.ts

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

package/src/surfaces/admin/components/DateField/examples/multiple-datefield.example.ts

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

package/src/surfaces/admin/components/DateField/examples/range-datefield.example.ts

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

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

@@ -0,0 +1,83 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'DatePicker',
+  description:
+    'Date pickers let merchants choose dates from a visual calendar that’s consistently applied wherever dates need to be selected across Shopify.    ',
+  requires: '',
+  thumbnail: 'datepicker-thumbnail.png',
+  isVisualComponent: true,
+  type: '',
+  definitions: [
+    {
+      title: 'DatePickerProps',
+      description: '',
+      type: 'DatePickerProps',
+    },
+  ],
+  category: 'Components',
+  subCategory: 'Forms',
+  defaultExample: {
+    image: 'datepicker-default.png',
+    codeblock: {
+      title: 'Add a single-date DatePicker',
+      tabs: [
+        {
+          title: 'React',
+          code: '../../../../../../ui-extensions-react/src/surfaces/admin/components/DatePicker/examples/basic-datepicker.example.tsx',
+          language: 'tsx',
+        },
+        {
+          title: 'JS',
+          code: './examples/basic-datepicker.example.ts',
+          language: 'js',
+        },
+      ],
+    },
+  },
+  examples: {
+    description: '',
+    examples: [
+      {
+        description: 'Use this when merchants need to select multiple dates.',
+        codeblock: {
+          title: 'Add a multi-date DatePicker',
+          tabs: [
+            {
+              title: 'React',
+              code: '../../../../../../ui-extensions-react/src/surfaces/admin/components/DatePicker/examples/multiple-datepicker.example.tsx',
+              language: 'tsx',
+            },
+            {
+              title: 'JS',
+              code: './examples/multiple-datepicker.example.ts',
+              language: 'js',
+            },
+          ],
+        },
+      },
+      {
+        description: 'Use this when merchants need to select a range of dates.',
+        codeblock: {
+          title: 'Add a range DatePicker',
+          tabs: [
+            {
+              title: 'React',
+              code: '../../../../../../ui-extensions-react/src/surfaces/admin/components/DatePicker/examples/range-datepicker.example.tsx',
+              language: 'tsx',
+            },
+            {
+              title: 'JS',
+              code: './examples/range-datepicker.example.ts',
+              language: 'js',
+            },
+          ],
+        },
+      },
+    ],
+  },
+
+  related: [],
+};
+
+export default data;

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

@@ -0,0 +1,100 @@
+import {createRemoteComponent} from '@remote-ui/core';
+
+export interface DatePickerProps<T extends Selected> {
+  /**
+   * [Controlled](https://reactjs.org/docs/forms.html#controlled-components) year and month to display.
+   * Use in combination with `onYearMonthChange`.
+   * Makes year/month navigation [controlled](https://reactjs.org/docs/forms.html#controlled-components).
+   */
+  yearMonth?: {year: Year; month: Month} | YearMonthString;
+
+  /**
+   * Default [uncontrolled](https://reactjs.org/docs/forms.html#controlled-components) year and month to display.
+   * Ignored when year/month navigation is [controlled](https://reactjs.org/docs/forms.html#controlled-components).
+   */
+  defaultYearMonth?: {year: Year; month: Month} | YearMonthString;
+
+  /**
+   * Disabled dates, days, and/or ranges, or the date picker.
+   * Unbound range disables all dates either from `start` date or to `end` date.
+   * `true` disables the date picker.
+   */
+  disabled?: Disabled | Disabled[] | boolean;
+
+  /**
+   * Whether the date picker is read-only.
+   */
+  readOnly?: boolean;
+
+  /**
+   * A date, an array of dates, or a range object with `start` and/or `end` keys indicating the selected dates.
+   * When a range is set, dates between the boundaries will be selected.
+   * Passed `undefined` or `string` allows user to select a single date,
+   * an empty array or an array of dates allows selecting multiple dates,
+   * an empty object or a Range object allows selecting a range of dates.
+   */
+  selected?: T;
+
+  /**
+   * A callback that is run whenever a date is selected or unselected. This callback
+   * is called with a string, an array of strings or a range object representing the selected dates.
+   * This component is [controlled](https://reactjs.org/docs/forms.html#controlled-components),
+   * so you must store these values in state and reflect it back in the
+   * `selected` props.
+   */
+  onChange?(selected: T): void;
+
+  /**
+   * A callback that is run whenever the month is changed. This callback
+   * is called with an object indicating the year/month the UI should change to.
+   * When year/month navigation is controlled you must store these values in state and
+   * reflect it back in the `yearMonth` prop.
+   */
+  onYearMonthChange?(yearMonth: {year: Year; month: Month}): void;
+}
+
+/**
+ * A date string using the simplified ISO 8601 format (`YYYY-MM-DD`)
+ */
+export type DateString = string;
+
+/**
+ * A year/month string using the simplified ISO 8601 format (`YYYY-MM`)
+ */
+export type YearMonthString = string;
+
+/**
+ * Month in 1-12 range
+ */
+export type Month = number;
+
+export type Year = number;
+
+export type Day =
+  | 'Sunday'
+  | 'Monday'
+  | 'Tuesday'
+  | 'Wednesday'
+  | 'Thursday'
+  | 'Friday'
+  | 'Saturday';
+
+export type Selected = DateString | DateString[] | Range;
+export type Disabled = DateString | Range | Day;
+
+export interface Range {
+  /**
+   * First day (inclusive) of the selected range
+   */
+  start?: DateString;
+
+  /**
+   * Last day (inclusive) of the selected range
+   */
+  end?: DateString;
+}
+
+export const DatePicker = createRemoteComponent<
+  'DatePicker',
+  DatePickerProps<Selected>
+>('DatePicker');