expose picker only to block extensions and add static doc section

packages/ui-extensions/docs/surfaces/admin/staticPages/admin-extensions.doc.ts

@@ -55,6 +55,12 @@ const data: LandingTemplateSchema = {
           url: '#direct-api-access',
           type: 'tool',
         },
+        {
+          subtitle: 'Picking resources',
+          name: 'Display resource pickers to select resources',
+          url: '#picking-resources',
+          type: 'tool',
+        },
         {
           subtitle: 'Custom protocols',
           name: 'Easily construct URLs to navigate to common locations',
@@ -166,6 +172,47 @@ const data: LandingTemplateSchema = {
         },
       ],
     },
+    {
+      type: 'GenericAccordion',
+      title: 'Picking Resources',
+      sectionContent:
+        "Use the Resource Picker and Picker API's to allow users to select resources for your extension to use.",
+      anchorLink: 'picking-resources',
+      accordionContent: [
+        {
+          title: 'Resource Picker',
+          description:
+            'Use the `resourcePicker` API to display a search-based interface to help users find and select one or more products, collections, or product variants, and then return the selected resources to your extension. Both the app and the user must have the necessary permissions to access the resources selected.',
+          image: 'resource-picker.png',
+          codeblock: {
+            title: 'resourcePicker',
+            tabs: [
+              {
+                title: 'Selecting a product',
+                language: 'tsx',
+                code: './examples/resource-picker-product.jsx',
+              },
+            ],
+          },
+        },
+        {
+          title: 'Picker',
+          description:
+            'Use the `picker` API to display a search-based interface to help users find and select one or more custom data types that you provide, such as product reviews, email templates, or subscription options.',
+          image: 'picker.png',
+          codeblock: {
+            title: 'picker',
+            tabs: [
+              {
+                title: 'Selecting an email template',
+                language: 'tsx',
+                code: './examples/picker-email-template.jsx',
+              },
+            ],
+          },
+        },
+      ],
+    },
     {
       type: 'GenericAccordion',
       title: 'Custom Protocols',

packages/ui-extensions/docs/surfaces/admin/staticPages/examples/picker-email-template.jsx

@@ -0,0 +1,56 @@
+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 {picker} = useApi(TARGET);
+
+  const handleSelectEmailTemplate = async () => {
+    const pickerInstance = await picker({
+      heading: 'Select a template',
+      multiple: false,
+      headers: [
+        {content: 'Templates'},
+        {content: 'Created by'},
+        {content: '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: ['Charlie Mitchell', '5'],
+          badges: [
+            {content: 'Published', tone: 'success'},
+            {content: 'New feature'},
+          ],
+          selected: true,
+        },
+        {
+          id: '3',
+          heading: 'Promo header, 2 column',
+          data: ['Russell Winfield', '10'],
+          badges: [{content: 'Published', tone: 'success'}],
+        },
+      ],
+    });
+
+    const selected = await pickerInstance.selected;
+    console.log(selected);
+  };
+
+  return (
+    <Button onClick={handleSelectEmailTemplate}>Select email template</Button>
+  );
+}

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 handleSelectProduct = async () => {
+    const selected = await resourcePicker({type: 'product'});
+    console.log(selected);
+  };
+
+  return <Button onClick={handleSelectProduct}>Select product</Button>;
+}

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 {
   /**
@@ -29,4 +30,9 @@ export interface BlockExtensionApi<ExtensionTarget extends AnyExtensionTarget>
    * 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.
    */
   resourcePicker: ResourcePickerApi;
+
+  /**
+   * Renders the [Picker](/docs/api/app-bridge-library/apis/picker), allowing users to select a resource for the extension to use as part of its flow.
+   */
+  picker: PickerApi;
 }

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

@@ -1,7 +1,6 @@
 import type {I18n} from '../../../../api';
 import {ApiVersion} from '../../../../shared';
 import type {ExtensionTarget as AnyExtensionTarget} from '../../extension-targets';
-import {PickerApi} from '../picker/picker';
 
 export interface Intents {
   /**
@@ -62,9 +61,4 @@ export interface StandardApi<ExtensionTarget extends AnyExtensionTarget> {
     query: string,
     options?: {variables?: Variables; version?: Omit<ApiVersion, '2023-04'>},
   ) => Promise<{data?: Data; errors?: GraphQLError[]}>;
-
-  /**
-   * Renders the [Picker](/docs/api/app-bridge-library/apis/picker), allowing users to select a resource for the extension to use as part of its flow.
-   */
-  picker: PickerApi;
 }