From 432358a72b6b18c971f21e17f610b4fe906151cd Mon Sep 17 00:00:00 2001 From: Charlie Dobson Date: Mon, 18 Nov 2024 15:01:17 -0500 Subject: [PATCH] expose picker only to block extensions and add static doc section --- .../admin/staticPages/admin-extensions.doc.ts | 47 ++++++++++++++++ .../examples/picker-email-template.jsx | 56 +++++++++++++++++++ .../examples/resource-picker-product.jsx | 20 +++++++ .../src/surfaces/admin/api/block/block.ts | 6 ++ .../surfaces/admin/api/standard/standard.ts | 6 -- 5 files changed, 129 insertions(+), 6 deletions(-) create mode 100644 packages/ui-extensions/docs/surfaces/admin/staticPages/examples/picker-email-template.jsx create mode 100644 packages/ui-extensions/docs/surfaces/admin/staticPages/examples/resource-picker-product.jsx diff --git a/packages/ui-extensions/docs/surfaces/admin/staticPages/admin-extensions.doc.ts b/packages/ui-extensions/docs/surfaces/admin/staticPages/admin-extensions.doc.ts index 62c1ab48e..f48ad22aa 100644 --- a/packages/ui-extensions/docs/surfaces/admin/staticPages/admin-extensions.doc.ts +++ b/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', diff --git a/packages/ui-extensions/docs/surfaces/admin/staticPages/examples/picker-email-template.jsx b/packages/ui-extensions/docs/surfaces/admin/staticPages/examples/picker-email-template.jsx new file mode 100644 index 000000000..b3aef91bc --- /dev/null +++ b/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, () => ); + +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 ( + + ); +} diff --git a/packages/ui-extensions/docs/surfaces/admin/staticPages/examples/resource-picker-product.jsx b/packages/ui-extensions/docs/surfaces/admin/staticPages/examples/resource-picker-product.jsx new file mode 100644 index 000000000..7809adeb1 --- /dev/null +++ b/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, () => ); + +function App() { + const {resourcePicker} = useApi(TARGET); + + const handleSelectProduct = async () => { + const selected = await resourcePicker({type: 'product'}); + console.log(selected); + }; + + return ; +} diff --git a/packages/ui-extensions/src/surfaces/admin/api/block/block.ts b/packages/ui-extensions/src/surfaces/admin/api/block/block.ts index db35e92d9..fd68bf8ac 100644 --- a/packages/ui-extensions/src/surfaces/admin/api/block/block.ts +++ b/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 * 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; } diff --git a/packages/ui-extensions/src/surfaces/admin/api/standard/standard.ts b/packages/ui-extensions/src/surfaces/admin/api/standard/standard.ts index 264fcee94..7b28f9fd8 100644 --- a/packages/ui-extensions/src/surfaces/admin/api/standard/standard.ts +++ b/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 { query: string, options?: {variables?: Variables; version?: Omit}, ) => 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; }