Merge pull request #2379 from Shopify/generic-picker

Add picker API

.changeset/lemon-dots-rhyme.md

@@ -0,0 +1,7 @@
+---
+'@shopify/ui-extensions-react': minor
+'@shopify/data-extensions': minor
+'@shopify/ui-extensions': minor
+---
+
+Add Picker

.changeset/sweet-toes-taste.md

@@ -0,0 +1,5 @@
+---
+'@shopify/ui-extensions': patch
+---
+
+Sync picker and resourcePicker docs with app-bridge

packages/ui-extensions/docs/surfaces/admin/staticPages/examples/resource-picker-product.jsx

@@ -0,0 +1,20 @@
+import {
+  reactExtension,
+  useApi,
+  Button,
+} from '@shopify/ui-extensions-react/admin';
+
+const TARGET = 'admin.product-details.block.render';
+
+export default reactExtension(TARGET, () => <App />);
+
+function App() {
+  const {resourcePicker} = useApi(TARGET);
+
+  const selectProduct = async () => {
+    const selected = await resourcePicker({type: 'product'});
+    console.log(selected);
+  };
+
+  return <Button onClick={selectProduct}>Select product</Button>;
+}

packages/ui-extensions/src/surfaces/admin/api/action/action.doc.ts

@@ -14,6 +14,7 @@ const data: ReferenceEntityTemplateSchema = {
     },
   ],
   category: 'API',
+  subCategory: 'Target APIs',
   related: [],
 };
 

packages/ui-extensions/src/surfaces/admin/api/block/block.doc.ts

@@ -14,6 +14,7 @@ const data: ReferenceEntityTemplateSchema = {
     },
   ],
   category: 'API',
+  subCategory: 'Target APIs',
   related: [],
 };
 

packages/ui-extensions/src/surfaces/admin/api/block/block.ts

@@ -2,6 +2,7 @@ import type {StandardApi} from '../standard/standard';
 import type {ExtensionTarget as AnyExtensionTarget} from '../../extension-targets';
 import type {Data} from '../shared';
 import type {ResourcePickerApi} from '../resource-picker/resource-picker';
+import type {PickerApi} from '../picker/picker';
 
 export interface Navigation {
   /**
@@ -26,7 +27,12 @@ export interface BlockExtensionApi<ExtensionTarget extends AnyExtensionTarget>
   navigation: Navigation;
 
   /**
-   * Renders the [Resource Picker](/docs/api/app-bridge-library/apis/resource-picker), allowing users to select a resource for the extension to use as part of its flow.
+   * Renders the [Resource Picker](resource-picker), allowing users to select a resource for the extension to use as part of its flow.
    */
   resourcePicker: ResourcePickerApi;
+
+  /**
+   * Renders a custom [Picker](picker) dialog allowing users to select values from a list.
+   */
+  picker: PickerApi;
 }

packages/ui-extensions/src/surfaces/admin/api/checkout-rules/validation-settings.doc.ts

@@ -19,6 +19,7 @@ const data: ReferenceEntityTemplateSchema = {
     },
   ],
   category: 'API',
+  subCategory: 'Target APIs',
   related: [],
 };
 

packages/ui-extensions/src/surfaces/admin/api/customer-segment-template/customer-segment-template.doc.ts

@@ -14,6 +14,7 @@ const data: ReferenceEntityTemplateSchema = {
     },
   ],
   category: 'API',
+  subCategory: 'Target APIs',
   related: [],
 };
 

packages/ui-extensions/src/surfaces/admin/api/picker/examples/direct-api.js

@@ -0,0 +1,73 @@
+const r = await fetch('shopify:admin/api/graphql.json', {
+  method: 'POST',
+  body: JSON.stringify({
+    query: `
+      query GetOrders($first: Int!) {
+        orders(first: $first) {
+          edges {
+            node {
+              id
+              name
+              customer {
+                displayName
+              }
+              originalTotalPriceSet {
+                shopMoney {
+                  amount
+                }
+              }
+              displayFulfillmentStatus
+              displayFinancialStatus
+              unpaid
+            }
+          }
+        }
+      }
+    `,
+    variables: {first: 10},
+  }),
+});
+const {data} = await r.json();
+const orderData = data.orders.edges;
+
+const selected = await picker({
+  heading: 'Select orders',
+  multiple: true,
+  headers: [
+    {title: 'Order'},
+    {title: 'Customer'},
+    {title: 'Total', type: 'number'},
+  ],
+  items: orderData.map((order) => {
+    const {
+      id,
+      name,
+      customer,
+      originalTotalPriceSet: {shopMoney},
+      displayFulfillmentStatus,
+      displayFinancialStatus,
+    } = order.node;
+
+    return {
+      id,
+      heading: name,
+      data: [customer.displayName, `$${shopMoney.amount}`],
+      badges: [
+        {
+          content: displayFulfillmentStatus,
+          tone: displayFulfillmentStatus === 'FULFILLED' ? '' : 'attention',
+          progress:
+            displayFulfillmentStatus === 'FULFILLED'
+              ? 'complete'
+              : 'incomplete',
+        },
+        {
+          content: displayFinancialStatus,
+          tone: displayFinancialStatus === 'PENDING' ? 'warning' : '',
+          progress:
+            displayFinancialStatus === 'PENDING' ? 'incomplete' : 'complete',
+        },
+      ],
+    };
+  }),
+});

packages/ui-extensions/src/surfaces/admin/api/picker/examples/disabled.js

@@ -0,0 +1,16 @@
+const pickerInstance = await picker({
+  heading: 'Disabled items',
+  items: [
+    {
+      id: '1',
+      heading: 'Item 1',
+      disabled: true,
+    },
+    {
+      id: '2',
+      heading: 'Item 2',
+    },
+  ],
+});
+
+const selected = await pickerInstance.selected;

packages/ui-extensions/src/surfaces/admin/api/picker/examples/minimal.js

@@ -0,0 +1,16 @@
+const pickerInstance = await picker({
+  heading: 'Select an item',
+  headers: [{title: 'Main heading'}],
+  items: [
+    {
+      id: '1',
+      heading: 'Item 1',
+    },
+    {
+      id: '2',
+      heading: 'Item 2',
+    },
+  ],
+});
+
+const selected = await pickerInstance.selected;

packages/ui-extensions/src/surfaces/admin/api/picker/examples/multiple-limit.js

@@ -0,0 +1,21 @@
+const pickerInstance = await picker({
+  heading: 'Select items (up to 2)',
+  multiple: 2,
+  headers: [{title: 'Main heading'}],
+  items: [
+    {
+      id: '1',
+      heading: 'Item 1',
+    },
+    {
+      id: '2',
+      heading: 'Item 2',
+    },
+    {
+      id: '3',
+      heading: 'Item 3',
+    },
+  ],
+});
+
+const selected = await pickerInstance.selected;

packages/ui-extensions/src/surfaces/admin/api/picker/examples/multiple-true.js

@@ -0,0 +1,21 @@
+const pickerInstance = await picker({
+  heading: 'Select items',
+  multiple: true,
+  headers: [{title: 'Main heading'}],
+  items: [
+    {
+      id: '1',
+      heading: 'Item 1',
+    },
+    {
+      id: '2',
+      heading: 'Item 2',
+    },
+    {
+      id: '3',
+      heading: 'Item 3',
+    },
+  ],
+});
+
+const selected = await pickerInstance.selected;

packages/ui-extensions/src/surfaces/admin/api/picker/examples/preselected.js

@@ -0,0 +1,16 @@
+const pickerInstance = await picker({
+  heading: 'Preselected items',
+  items: [
+    {
+      id: '1',
+      heading: 'Item 1',
+      selected: true,
+    },
+    {
+      id: '2',
+      heading: 'Item 2',
+    },
+  ],
+});
+
+const selected = await pickerInstance.selected;

packages/ui-extensions/src/surfaces/admin/api/picker/examples/template-picker.js

@@ -0,0 +1,37 @@
+const {picker} = useApi(TARGET);
+
+const pickerInstance = await picker({
+  heading: 'Select a template',
+  multiple: false,
+  headers: [
+    {title: 'Templates'},
+    {title: 'Created by'},
+    {title: 'Times used', type: 'number'},
+  ],
+  items: [
+    {
+      id: '1',
+      heading: 'Full width, 1 column',
+      data: ['Karine Ruby', '0'],
+      badges: [{content: 'Draft', tone: 'info'}, {content: 'Marketing'}],
+    },
+    {
+      id: '2',
+      heading: 'Large graphic, 3 column',
+      data: ['Russell Winfield', '5'],
+      badges: [
+        {content: 'Published', tone: 'success'},
+        {content: 'New feature'},
+      ],
+      selected: true,
+    },
+    {
+      id: '3',
+      heading: 'Promo header, 2 column',
+      data: ['Russel Winfield', '10'],
+      badges: [{content: 'Published', tone: 'success'}],
+    },
+  ],
+});
+
+const selected = await pickerInstance.selected;