@shopify/ui-extensions 0.0.0-internal-20230622171951

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

@@ -0,0 +1,42 @@
+import {createRemoteComponent} from '@remote-ui/core';
+
+interface OptionDescriptor {
+  /** Value of the option */
+  value: string;
+
+  /** Display label for the option */
+  label: string;
+
+  /** Whether the option is disabled or not */
+  disabled?: boolean;
+}
+
+export interface OptionListProps {
+  /** Title to display above the list */
+  title?: string;
+
+  /** Array of options to be listed */
+  options?: OptionDescriptor[];
+
+  /** Array of selected options */
+  selected: string[];
+
+  /** Allow more than one option to be selected */
+  allowMultiple?: boolean;
+
+  /**
+   * Callback when selection changes
+   * @param selected Array of selected options
+   * */
+  onChange(selected: string[]): void;
+}
+
+/**
+ * **Note:** This component is not available in Product Subscription extensions.
+ *
+ * Option lists let you create grouped items. This can include single selection or multiple selection of options.
+ * Option lists are styled differently than choice lists and should not be used within a form, but as a standalone menu.
+ */
+export const OptionList = createRemoteComponent<'OptionList', OptionListProps>(
+  'OptionList',
+);

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

@@ -0,0 +1,7 @@
+## Guidelines
+
+| ✅ Do                                                                 | 🛑 Don't                |
+| --------------------------------------------------------------------- | ----------------------- |
+| Use OptionList to present either a single choice or multi choice list | Have only a single item |
+
+For more guidelines, refer to Polaris' [Option List best practices](https://polaris.shopify.com/components/lists-and-tables/option-list#section-best-practices).

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

@@ -0,0 +1,24 @@
+import {extension, OptionList} from '@shopify/ui-extensions/admin';
+
+export default extension('Playground', (root) => {
+  const options = [
+    {label: 'Red', value: 'red', disabled: false},
+    {label: 'Green', value: 'green', disabled: false},
+    {label: 'Blue', value: 'blue', disabled: false},
+  ];
+  let selected = [];
+
+  const list = root.createComponent(OptionList, {
+    title: 'OptionList title',
+    options,
+    allowMultiple: true,
+    selected,
+    onChange: (newSelected) => {
+      console.log(`option selected: ${newSelected}`);
+      selected = newSelected;
+    },
+  });
+  root.appendChild(list);
+
+  root.mount();
+});

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

@@ -0,0 +1,14 @@
+import {createRemoteComponent} from '@remote-ui/core';
+
+export interface PressableProps {
+  /** Callback for the pressable. */
+  onPress: () => void;
+}
+
+/**
+ * Pressable wraps components to add interactivity with rendering a UI element.
+ * Wrap small UI elements in Pressable to perform actions that don’t fit Button or Link.
+ */
+export const Pressable = createRemoteComponent<'Pressable', PressableProps>(
+  'Pressable',
+);

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

@@ -0,0 +1,12 @@
+## Guidelines
+
+- 📱 All children of Pressables are placed in a single view object, which makes recycling the views expensive. Consider keeping your Pressable simple.
+- 📱 Do not nest Layouts within Pressable. This will result in unintended behavior
+- Do not nest other Action components (Button, Link) within Pressable. This will result in unexpected behavior.
+  - 📱 A child of Pressable with `onPress` will take precedence and not call Pressable's `onPress`
+  - 🖥 Both the child of Pressable with `onPress` and Pressable's `onPress` will activate if the child is pressed.
+
+| ✅ Do                                                                                 | 🛑 Don't               |
+| ------------------------------------------------------------------------------------- | ---------------------- |
+| 📱 Keep Pressable shallow. Complex hierarchies have performance penalties             | Wrap Button or Link    |
+| Wrap small UI elements in Pressable to perform actions that don’t fit Button or Link. | Wrap Layout components |

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

@@ -0,0 +1,15 @@
+import {extension, Pressable, Text} from '@shopify/ui-extensions/admin';
+
+export default extension('Playground', (root) => {
+  const pressable = root.createComponent(Pressable, {
+    onPress: () => console.log('I’ve been pressed!'),
+  });
+
+  const pressableText = root.createComponent(Text);
+  pressableText.appendChild('I can be pressed');
+
+  pressable.appendChild(pressableText);
+  root.appendChild(pressable);
+
+  root.mount();
+});

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

@@ -0,0 +1,29 @@
+import {createRemoteComponent} from '@remote-ui/core';
+
+export interface RadioProps {
+  /** Label for the radio button. */
+  label?: string;
+
+  /** Additional text to aid in use. */
+  helpText?: string;
+
+  /** Radio button is selected. */
+  checked?: boolean;
+
+  /** Unique ID for radio button. */
+  id?: string;
+
+  /** Use `name` to group radio buttons together by giving them the same `name`. */
+  name: string;
+
+  /** Value of selected input on selected */
+  value?: string;
+
+  /** Callback when the radio button is toggled. */
+  onChange?: (newValue: string) => void;
+}
+
+/**
+ * Radio allows merchants to choose a single item from a list.
+ */
+export const Radio = createRemoteComponent<'Radio', RadioProps>('Radio');

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

@@ -0,0 +1,6 @@
+| ✅ Do                                              | 🛑 Don't                         |
+| -------------------------------------------------- | -------------------------------- |
+| Use Radio to give merchants a single select choice | Horizontally stack Radio options |
+| Vertically align Radio options                     |                                  |
+
+For more guidelines, refer to Polaris' [Radio button best practices](https://polaris.shopify.com/components/forms/radio-button#section-best-practices).

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

@@ -0,0 +1,25 @@
+import {extension, Radio} from '@shopify/ui-extensions/admin';
+
+export default extension('Playground', (root) => {
+  const radio1 = root.createComponent(Radio, {
+    label: 'Option 1',
+    helpText: 'Help text for option 1.',
+    checked: true,
+    id: 'option1',
+    name: 'greatOptions',
+    onChange: () => console.log('Option 1 selected'),
+  });
+
+  const radio2 = root.createComponent(Radio, {
+    label: 'Option 2',
+    helpText: 'Help text for option 2.',
+    id: 'option2',
+    name: 'greatOptions',
+    checked: false,
+    onChange: () => console.log('Option 2 selected'),
+  });
+
+  root.appendChild(radio1);
+  root.appendChild(radio2);
+  root.mount();
+});

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

@@ -0,0 +1,19 @@
+import {createRemoteComponent} from '@remote-ui/core';
+
+export interface ResourceItemProps {
+  /** Unique ID for the resource item. */
+  id: string;
+
+  /** Callback when the resource item is pressed. */
+  onPress(): void;
+}
+
+/**
+ * Resource items represent specific objects within a collection, such as products or orders. They provide contextual information on the resource type and link to the object’s detail page.
+ *
+ * A `ResourceItem` should be rendered within a `ResourceList`.
+ */
+export const ResourceItem = createRemoteComponent<
+  'ResourceItem',
+  ResourceItemProps
+>('ResourceItem');

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

@@ -0,0 +1,8 @@
+## Behavior
+
+- 📱 All children of ResourceItems are placed in a single view object, which makes recycling the views expensive. Consider making your ResourceItems simple.
+- 📱 Any child of ResourceItem that has an `onPress` will take precedence and the `onPress` of ResourceItem will not be invoked
+
+| ✅ Do                                                                        | 🛑 Don't                              |
+| ---------------------------------------------------------------------------- | ------------------------------------- |
+| 📱 Keep ResourceItem shallow. Complex hierarchies have performance penalties | 📱 Use complex and deep Stack layouts |

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

@@ -0,0 +1,22 @@
+import {extension, ResourceList, ResourceItem} from '@shopify/ui-extensions/admin';
+
+export default extension('Playground', (root) => {
+  const resourceItem1 = root.createComponent(ResourceItem, {
+    id: '1234',
+    onPress: () => console.log('Pressed 1'),
+  });
+  resourceItem1.appendChild('Cool item');
+  const resourceItem2 = root.createComponent(ResourceItem, {
+    id: '5678',
+    onPress: () => console.log('Pressed 2'),
+  });
+  resourceItem2.appendChild('Cooler item');
+
+  const resourceList = root.createComponent(ResourceList, {});
+
+  resourceList.appendChild(resourceItem1);
+  resourceList.appendChild(resourceItem2);
+
+  root.appendChild(resourceList);
+  root.mount();
+});

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

@@ -0,0 +1,30 @@
+import {createRemoteComponent} from '@remote-ui/core';
+
+interface FilterControl {
+  /** Search query value */
+  queryValue?: string;
+
+  /** Placeholder for search query field */
+  queryPlaceholder?: string;
+
+  /** Callback when search query changes */
+  onQueryChange(queryValue: string): void;
+
+  /** Callback when the search field is cleared */
+  onQueryClear(): void;
+}
+
+export interface ResourceListProps {
+  filterControl?: FilterControl;
+}
+
+/**
+ * `ResourceList` displays a filterable collection of objects of the same type, like products or customers.
+ *
+ * `ResourceList` should help merchants find an object and navigate to a full-page representation of it.
+ * A resource list should contain `ResourceItem` components.
+ */
+export const ResourceList = createRemoteComponent<
+  'ResourceList',
+  ResourceListProps
+>('ResourceList');

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

@@ -0,0 +1,9 @@
+## Guidelines
+
+A resource list should contain only `ResourceItem` components.
+
+| ✅ Do                                              | 🛑 Don't                                                           |
+| -------------------------------------------------- | ------------------------------------------------------------------ |
+| Use ResourceList to show a summary of the resource | ResourceLists should not contain elements other than ResourceItems |
+
+For more guidelines, refer to Polaris' [Resource List best practices](https://polaris.shopify.com/components/lists-and-tables/resource-list#section-best-practices).

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

@@ -0,0 +1,29 @@
+import {extension, ResourceList, ResourceItem} from '@shopify/ui-extensions/admin';
+
+export default extension('Playground', (root) => {
+  const resourceitem1 = root.createComponent(ResourceItem, {
+    id: '1234',
+    onPress: () => console.log('Pressed 1'),
+  });
+  resourceitem1.appendChild('Cool item');
+  const resourceitem2 = root.createComponent(ResourceItem, {
+    id: '5678',
+    onPress: () => console.log('Pressed 2'),
+  });
+  resourceitem2.appendChild('Cooler item');
+
+  const resourcelist = root.createComponent(ResourceList, {
+    filterControl: {
+      queryValue: '123',
+      queryPlaceholder: 'Filter list',
+      onQueryChange: (queryValue) => console.log('Filtering for', queryValue),
+      onQueryClear: () => console.log('Clear value'),
+    },
+  });
+
+  resourcelist.appendChild(resourceitem1);
+  resourcelist.appendChild(resourceitem2);
+
+  root.appendChild(resourcelist);
+  root.mount();
+});

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

@@ -0,0 +1,39 @@
+import {createRemoteComponent} from '@remote-ui/core';
+
+interface Option {
+  /** Rendered */
+  label: string;
+
+  /** Non-rendered */
+  value: string;
+}
+
+export interface SelectProps {
+  /** Display an error state */
+  error?: string;
+
+  /** Label for the select. */
+  label: string;
+
+  /** Show the label to the left of the value, inside the control. */
+  labelInline?: boolean;
+
+  /** Array of Options to select from. */
+  options: Option[];
+
+  /** Callback when selected Option changes. */
+  onChange?: (value: string) => void;
+
+  /** Callback when focus is removed */
+  onBlur?: () => void;
+
+  /** The value of the currently selected Option. */
+  value?: string;
+}
+
+/**
+ * Select allows merchants to choose one option from a dropdown menu.
+ *
+ * Consider Select when you have 4 or more options, to avoid creating clutter and make your component more scalable.
+ */
+export const Select = createRemoteComponent<'Select', SelectProps>('Select');

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

@@ -0,0 +1,7 @@
+## Guidelines
+
+| ✅ Do                                      | 🛑 Don't                |
+| ------------------------------------------ | ----------------------- |
+| Use Select when you have 4 or more options | Have only a single item |
+
+For more guidelines, refer to Polaris' [Select best practices](https://polaris.shopify.com/components/forms/select#section-best-practices).

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

@@ -0,0 +1,30 @@
+import {extension, Select} from '@shopify/ui-extensions/admin';
+
+const options = [
+  {
+    label: 'Cool option',
+    value: 'cool-option',
+  },
+  {
+    label: 'Cooler option',
+    value: 'cooler-option',
+  },
+  {
+    label: 'Coolest option',
+    value: 'coolest-option',
+  },
+];
+
+export default extension('Playground', (root) => {
+  const select = root.createComponent(Select, {
+    label: 'Select an option',
+    options,
+    labelInline: true,
+    onChange: (value) => console.log(value, 'was selected'),
+    value: 'cooler-option',
+  });
+
+  root.appendChild(select);
+
+  root.mount();
+});

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

@@ -0,0 +1,10 @@
+import {createRemoteComponent} from '@remote-ui/core';
+
+export interface SpinnerProps {}
+
+/**
+ * Spinners are used to show merchants that your app is loading, or an action is being performed. Generally when a spinner is being used, the user shouldn't be able to interact.
+ */
+export const Spinner = createRemoteComponent<'Spinner', SpinnerProps>(
+  'Spinner',
+);

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

@@ -0,0 +1,5 @@
+| ✅ Do                                                                        | 🛑 Don't                                                                                                                 |
+| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| Use Spinner to show that content is loading, or an action is being processed | Don’t place Spinners for each loading element. Rather, Spinners should be at the top level of the section they apply to. |
+
+For more guidelines, refer to Polaris' [Spinner best practices](https://polaris.shopify.com/components/feedback-indicators/spinner#section-best-practices).

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

@@ -0,0 +1,12 @@
+import {extension, Spinner} from '@shopify/ui-extensions/admin';
+
+export default extension('Playground', (root) => {
+  const spinner = root.createComponent(Spinner);
+  root.appendChild(spinner);
+
+  setTimeout(() => {
+    root.removeChild(spinner);
+  }, 2000);
+
+  root.mount();
+});

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

@@ -0,0 +1,15 @@
+import {createRemoteComponent} from '@remote-ui/core';
+
+export interface StackItemProps {
+  /** Fill the remaining horizontal space in the stack with this item  */
+  fill?: boolean;
+}
+
+/**
+ * By default, each individual element in a Stack is treated as one stack item.
+ *
+ * Wrap multiple elements in a `StackItem` component, and the `Stack` component will treat them as one item.
+ */
+export const StackItem = createRemoteComponent<'StackItem', StackItemProps>(
+  'StackItem',
+);

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

@@ -0,0 +1,8 @@
+## Behavior
+
+- 📱 All children of StackItems are placed in a single view object, which makes recycling the views expensive. Consider keeping your StackItems simple.
+
+| ✅ Do                                                                      | 🛑 Don't                              |
+| -------------------------------------------------------------------------- | ------------------------------------- |
+| 📱 Keep StackItems shallow. Complex hierarchies have performance penalties | 📱 Use complex and deep Stack layouts |
+| Wrap small UI elements in StackItem to group UI elements and styles        | Use StackItems outside of Stacks      |

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

@@ -0,0 +1,25 @@
+import {extension, InlineStack, StackItem, Text} from '@shopify/ui-extensions/admin';
+
+export default extension('Playground', (root) => {
+  const stack = root.createComponent(InlineStack);
+  const stackItemFill = root.createComponent(StackItem, {fill: true});
+
+  const stackItemText = root.createComponent(Text);
+  stackItemText.appendChild('Fill the space');
+
+  const stackItemNoFill = root.createComponent(StackItem);
+  const text1 = root.createComponent(Text);
+  text1.appendChild('Other text');
+  const text2 = root.createComponent(Text);
+  text2.appendChild('Even more text');
+
+  stackItemFill.appendChild(stackItemText);
+  stack.appendChild(stackItemFill);
+
+  stackItemNoFill.appendChild(text1);
+  stackItemNoFill.appendChild(text2);
+  stack.appendChild(stackItemNoFill);
+
+  root.appendChild(stack);
+  root.mount();
+});

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

@@ -0,0 +1,26 @@
+import {createRemoteComponent} from '@remote-ui/core';
+
+export interface TextProps {
+  /* Changes the visual appearance */
+  appearance?: 'critical' | 'code' | 'subdued' | 'success';
+
+  /* Use to emphasize text that is more important than other nearby text */
+  emphasized?: boolean;
+
+  /**
+   * Unique identifier. Typically used as a target for another component’s controls
+   * to associate an accessible label with an action.
+   */
+  id?: string;
+
+  /* Size of the text */
+  size?: 'extraSmall' | 'small' | 'base' | 'medium' | 'large' | 'extraLarge';
+
+  /* Use for bold text that is more important than other nearby text */
+  strong?: boolean;
+}
+
+/**
+ * The Text component is used to render text in different sizes, colors, and alignments.
+ */
+export const Text = createRemoteComponent<'Text', TextProps>('Text');

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

@@ -0,0 +1,8 @@
+## Guidelines
+
+📱 Do not nest other components other than Text, they will be ignored and not rendered. Nested Text will be used to render the content of Text.
+
+| ✅ Do                                          | 🛑 Don't |
+| ---------------------------------------------- | -------- |
+| Use Text to add rich content to your extension |          |
+| Use size to (de)-emphasize your content        |          |

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

@@ -0,0 +1,20 @@
+import {extension, Text} from '@shopify/ui-extensions/admin';
+
+export default extension('Playground', (root) => {
+  const formattedText = root.createComponent(Text, {
+    appearance: 'success',
+    emphasized: true,
+    id: 'some_id',
+    size: 'small',
+    strong: true,
+  });
+  
+  formattedText.appendChild('Formatted text is awesome!');
+
+  const simpleText = root.createText('This simple text is a bit less awesome');
+
+  root.appendChild(formattedText);
+  root.appendChild(simpleText);
+
+  root.mount();
+});

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

@@ -0,0 +1,20 @@
+import {createRemoteComponent} from '@remote-ui/core';
+
+type Size = 'small' | 'base' | 'medium' | 'large' | 'extraLarge';
+
+type Variation = 'positive' | 'negative' | 'strong' | 'subdued' | 'code';
+
+export interface TextBlockProps {
+  /** Size of the text */
+  size?: Size;
+  /** Give text additional visual meaning */
+  variation?: Variation;
+}
+
+/**
+ * TextBlock is used to render a block of text that occupies the full width available.
+ * Usually used to render paragraphs of text.
+ */
+export const TextBlock = createRemoteComponent<'TextBlock', TextBlockProps>(
+  'TextBlock',
+);

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

@@ -0,0 +1,11 @@
+## Guidelines
+
+- `TextBlock` is used to render a block of text that occupies the full width available. Usually used to render paragraphs of text.
+- Use `variation` to give visual meaning to your content and `size` to adjust the font size.
+
+| ✅ Do                                             | 🛑 Don't |
+| ------------------------------------------------- | -------- |
+| Don’t rely on text style alone to convey          |          |
+| information to merchants. Ensure that text styles |          |
+| are used to enhance the information provided in   |          |
+| text.                                             |          |

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

@@ -0,0 +1,8 @@
+import {extension, TextBlock} from '@shopify/ui-extensions/admin';
+
+export default extension('Playground', (root) => {
+  const textBlock = root.createComponent(TextBlock, {size: 'small', variation: 'subdued'}, 'TextBlock');
+
+  root.appendChild(textBlock);
+  root.mount();
+});

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

@@ -0,0 +1,54 @@
+import {createRemoteComponent} from '@remote-ui/core';
+
+export interface TextFieldProps {
+  /** Human-readable label for the input. */
+  label: string;
+
+  /** Input type */
+  type?: 'text' | 'search' | 'number';
+
+  /** Input value. */
+  value?: string;
+
+  /** Hint text to display when no text is input */
+  placeholder?: string;
+
+  /** Allow for multiple lines of input. */
+  multiline?: number | boolean;
+
+  /** Text to display before the input value. */
+  prefix?: string;
+
+  /** Text to display after the input value. */
+  suffix?: string;
+
+  /** Error text to display beneath the label. */
+  error?: string;
+
+  /** Callback when value is changed. */
+  onInput?: (value: string) => void;
+
+  /** Callback when user leaves the input. */
+  onChange?: (value: string) => void;
+
+  /** Callback when input is focused. */
+  onFocus?(): void | Promise<void>;
+
+  /** Callback when focus is removed. */
+  onBlur?(): void | Promise<void>;
+
+  /** Show a 'clear text' button in the input. */
+  clearButton?: boolean;
+
+  /** Callback when clear button is pressed. */
+  onClearButtonPress?(): void;
+}
+
+/**
+ * TextField is a versatile input field that merchants can type into.
+ *
+ * It supports several input formats including numbers.
+ */
+export const TextField = createRemoteComponent<'TextField', TextFieldProps>(
+  'TextField',
+);

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

@@ -0,0 +1,10 @@
+## Guidelines
+
+- `TextField` will expand to the width of its container
+
+| ✅ Do                                        | 🛑 Don't                                     |
+| -------------------------------------------- | -------------------------------------------- |
+| 📱 Stack `TextField` components vertically   | 📱 Stack `TextField` components horizontally |
+| Use TextField to capture merchant text input |                                              |
+
+For more guidelines, refer to Polaris' [Text Field best practices](https://polaris.shopify.com/components/forms/text-field#section-best-practices).