diff --git a/.changeset/healthy-cups-wash.md b/.changeset/healthy-cups-wash.md new file mode 100644 index 000000000..375d76fef --- /dev/null +++ b/.changeset/healthy-cups-wash.md @@ -0,0 +1,5 @@ +--- +'@shopify/ui-extensions': minor +--- + +Add shouldRender method to ui-extensions diff --git a/packages/ui-extensions/src/surfaces/admin.ts b/packages/ui-extensions/src/surfaces/admin.ts index 9e6859777..d5a92f6ff 100644 --- a/packages/ui-extensions/src/surfaces/admin.ts +++ b/packages/ui-extensions/src/surfaces/admin.ts @@ -2,5 +2,6 @@ export * from './admin/api'; export * from './admin/components'; export * from './admin/extension-targets'; export * from './admin/extension'; +export * from './admin/shouldRender'; export * from './admin/shared'; export * from './admin/globals'; diff --git a/packages/ui-extensions/src/surfaces/admin/api/should-render/should-render.doc.ts b/packages/ui-extensions/src/surfaces/admin/api/should-render/should-render.doc.ts new file mode 100644 index 000000000..dcafc37b3 --- /dev/null +++ b/packages/ui-extensions/src/surfaces/admin/api/should-render/should-render.doc.ts @@ -0,0 +1,20 @@ +import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs'; + +const data: ReferenceEntityTemplateSchema = { + name: 'ShouldRender API', + description: + 'This API is available to all shouldRender extension types. Refer to the [tutorial](#) for more information.', + isVisualComponent: false, + type: 'API', + definitions: [ + { + title: 'ShouldRenderApi', + description: '', + type: 'ShouldRenderApi', + }, + ], + category: 'API', + related: [], +}; + +export default data; diff --git a/packages/ui-extensions/src/surfaces/admin/api/should-render/should-render.ts b/packages/ui-extensions/src/surfaces/admin/api/should-render/should-render.ts new file mode 100644 index 000000000..32726e7be --- /dev/null +++ b/packages/ui-extensions/src/surfaces/admin/api/should-render/should-render.ts @@ -0,0 +1,11 @@ +import type {StandardApi} from '../standard/standard'; +import type {ExtensionTarget as AnyExtensionTarget} from '../../extension-targets'; +import type {Data} from '../shared'; + +export interface ShouldRenderApi + extends StandardApi { + /** + * Information about the currently viewed or selected items. + */ + data: Data; +} diff --git a/packages/ui-extensions/src/surfaces/admin/should-render-targets.ts b/packages/ui-extensions/src/surfaces/admin/should-render-targets.ts new file mode 100644 index 000000000..c433661d5 --- /dev/null +++ b/packages/ui-extensions/src/surfaces/admin/should-render-targets.ts @@ -0,0 +1,299 @@ +import type {RunnableExtension} from '../../extension'; + +import {ShouldRenderApi} from './api/should-render/should-render'; + +interface ShouldRenderOutput { + display: boolean; +} + +export interface ExtensionTargets { + // Admin action shouldRender targets + /** + * Controls the render state of an admin action extension in the product details page. Open this extension from the "More Actions" menu. + */ + 'admin.product-details.action.render': RunnableExtension< + ShouldRenderApi<'admin.product-details.action.render'>, + ShouldRenderOutput + >; + + /** + * Controls the render state of an admin action extension in the catalog details page. Open this extension from the "More Actions" menu. + */ + 'admin.catalog-details.action.render': RunnableExtension< + ShouldRenderApi<'admin.catalog-details.action.render'>, + ShouldRenderOutput + >; + + /** + * Controls the render state of an admin action extension in the company details page. Open this extension from the "More Actions" menu. + */ + 'admin.company-details.action.render': RunnableExtension< + ShouldRenderApi<'admin.company-details.action.render'>, + ShouldRenderOutput + >; + + /** + * Controls the render state of an admin action extension in the gift card details page. Open this extension from the "More Actions" menu. + */ + 'admin.gift-card-details.action.render': RunnableExtension< + ShouldRenderApi<'admin.gift-card-details.action.render'>, + ShouldRenderOutput + >; + + /** + * Controls the render state of an admin action extension in the order details page. Open this extension from the "More Actions" menu. + */ + 'admin.order-details.action.render': RunnableExtension< + ShouldRenderApi<'admin.order-details.action.render'>, + ShouldRenderOutput + >; + + /** + * Controls the render state of an admin action extension in the customer details page. Open this extension from the "More Actions" menu. + */ + 'admin.customer-details.action.render': RunnableExtension< + ShouldRenderApi<'admin.customer-details.action.render'>, + ShouldRenderOutput + >; + + /** + * Controls the render state of an admin action extension in the customer segment details page. Open this extension from the "Use segment" button. + */ + 'admin.customer-segment-details.action.render': RunnableExtension< + ShouldRenderApi<'admin.customer-segment-details.action.render'>, + ShouldRenderOutput + >; + + /** + * Controls the render state of an admin action extension in the product index page. Open this extension from the "More Actions" menu. + */ + 'admin.product-index.action.render': RunnableExtension< + ShouldRenderApi<'admin.product-index.action.render'>, + ShouldRenderOutput + >; + + /** + * Controls the render state of an admin action extension in the order index page. Open this extension from the "More Actions" menu. + */ + 'admin.order-index.action.render': RunnableExtension< + ShouldRenderApi<'admin.order-index.action.render'>, + ShouldRenderOutput + >; + + /** + * Controls the render state of an admin action extension in the customer index page. Open this extension from the "More Actions" menu. + */ + 'admin.customer-index.action.render': RunnableExtension< + ShouldRenderApi<'admin.customer-index.action.render'>, + ShouldRenderOutput + >; + + /** + * Controls the render state of an admin action extension in the discount index page. Open this extension from the "More Actions" menu. + */ + 'admin.discount-index.action.render': RunnableExtension< + ShouldRenderApi<'admin.discount-index.action.render'>, + ShouldRenderOutput + >; + + /** + * Controls the render state of an admin action extension in the collection details page. Open this extension from the "More Actions" menu. + */ + 'admin.collection-details.action.render': RunnableExtension< + ShouldRenderApi<'admin.collection-details.action.render'>, + ShouldRenderOutput + >; + + /** + * Controls the render state of an admin action extension in the collection index page. Open this extension from the "More Actions" menu. + */ + 'admin.collection-index.action.render': RunnableExtension< + ShouldRenderApi<'admin.collection-index.action.render'>, + ShouldRenderOutput + >; + + /** + * Controls the render state of an admin action extension in the abandoned checkout page. Open this extension from the "More Actions" menu. + */ + 'admin.abandoned-checkout-details.action.render': RunnableExtension< + ShouldRenderApi<'admin.abandoned-checkout-details.action.render'>, + ShouldRenderOutput + >; + + /** + * Controls the render state of an admin action extension in the product variant details page. Open this extension from the "More Actions" menu. + */ + 'admin.product-variant-details.action.render': RunnableExtension< + ShouldRenderApi<'admin.product-variant-details.action.render'>, + ShouldRenderOutput + >; + + /** + * Controls the render state of an admin action extension in the draft order details page. Open this extension from the "More Actions" menu. + */ + 'admin.draft-order-details.action.render': RunnableExtension< + ShouldRenderApi<'admin.draft-order-details.action.render'>, + ShouldRenderOutput + >; + + /** + * Controls the render state of an admin action extension in the draft orders page. Open this extension from the "More Actions" menu. + */ + 'admin.draft-order-index.action.render': RunnableExtension< + ShouldRenderApi<'admin.draft-order-index.action.render'>, + ShouldRenderOutput + >; + + /** + * Controls the render state of an admin action extension in the discount details page. Open this extension from the "More Actions" menu. + */ + 'admin.discount-details.action.render': RunnableExtension< + ShouldRenderApi<'admin.discount-details.action.render'>, + ShouldRenderOutput + >; + + /** + * Controls the render state of an admin action extension in the order fulfilled card. Open this extension from the "3-dot" menu inside the order fulfilled card. + * Note: This extension will only be visible on orders which were fulfilled by your app. + */ + 'admin.order-fulfilled-card.action.render': RunnableExtension< + ShouldRenderApi<'admin.order-fulfilled-card.action.render'>, + ShouldRenderOutput + >; + + // Admin bulk action shouldRender targets + + /** + * Controls the render state of an admin action extension in the product index page when multiple resources are selected. Open this extension from the "More Actions" menu of the resource list. The resource ids are available to this extension at runtime. + */ + 'admin.product-index.selection-action.render': RunnableExtension< + ShouldRenderApi<'admin.product-index.selection-action.render'>, + ShouldRenderOutput + >; + + /** + * Controls the render state of an admin action extension in the order index page when multiple resources are selected. Open this extension from the "More Actions" menu of the resource list. The resource ids are available to this extension at runtime. + */ + 'admin.order-index.selection-action.render': RunnableExtension< + ShouldRenderApi<'admin.order-index.selection-action.render'>, + ShouldRenderOutput + >; + + /** + * Controls the render state of an admin action extension in the customer index page when multiple resources are selected. Open this extension from the "More Actions" menu of the resource list. The resource ids are available to this extension at runtime. + */ + 'admin.customer-index.selection-action.render': RunnableExtension< + ShouldRenderApi<'admin.customer-index.selection-action.render'>, + ShouldRenderOutput + >; + + /** + * Controls the render state of an admin action extension in the draft order page when multiple resources are selected. Open this extension from the "3-dot" menu. + */ + 'admin.draft-order-index.selection-action.render': RunnableExtension< + ShouldRenderApi<'admin.draft-order-index.selection-action.render'>, + ShouldRenderOutput + >; + + // Admin print action and bulk print action shouldRender targets + + /** + * Controls the render state of an admin print action extension in the order index page when multiple resources are selected. Open this extension from the "Print" menu of the resource list. The resource ids are available to this extension at runtime. + */ + 'admin.order-details.print-action.render': RunnableExtension< + ShouldRenderApi<'admin.order-details.print-action.render'>, + ShouldRenderOutput + >; + + /** + * Controls the render state of an admin print action extension in the product index page when multiple resources are selected. Open this extension from the "Print" menu of the resource list. The resource ids are available to this extension at runtime. + */ + 'admin.product-details.print-action.render': RunnableExtension< + ShouldRenderApi<'admin.product-details.print-action.render'>, + ShouldRenderOutput + >; + + /** + * Controls the render state of an admin print action extension in the order index page when multiple resources are selected. Open this extension from the "Print" menu of the resource list. The resource ids are available to this extension at runtime. + */ + 'admin.order-index.selection-print-action.render': RunnableExtension< + ShouldRenderApi<'admin.order-index.selection-print-action.render'>, + ShouldRenderOutput + >; + + /** + * Controls the render state of an admin print action extension in the product index page when multiple resources are selected. Open this extension from the "Print" menu of the resource list. The resource ids are available to this extension at runtime. + */ + 'admin.product-index.selection-print-action.render': RunnableExtension< + ShouldRenderApi<'admin.product-index.selection-print-action.render'>, + ShouldRenderOutput + >; +} + +export type ExtensionTarget = keyof ExtensionTargets; + +export type ExtensionForExtensionTarget = + ExtensionTargets[T]; + +/** + * For a given extension target, returns the value that is expected to be + * returned by that extension target’s callback type. + */ +export type ReturnTypeForExtension = + ReturnType; + +/** + * For a given extension target, returns the tuple of arguments that would + * be provided to that extension target’s callback type. + */ +export type ArgumentsForExtension = + Parameters; + +/** + * A union type containing all of the extension targets that follow the pattern of + * accepting a [`@remote-ui/core` `RemoteRoot`](https://github.com/Shopify/remote-dom/tree/remote-ui/packages/core) + * and an additional `api` argument, and using those arguments to render + * UI. + */ +export type RenderExtensionTarget = { + [ID in keyof ExtensionTargets]: ExtensionTargets[ID] extends RunnableExtension< + any, + any + > + ? ID + : never; +}[keyof ExtensionTargets]; + +/** + * A mapping of each “render extension” name to its callback type. + */ +export type RenderExtensions = { + [ID in RenderExtensionTarget]: ExtensionTargets[ID]; +}; + +type ExtractedApiFromRenderExtension = T extends RunnableExtension< + infer Api, + any +> + ? Api + : never; + +type ExtractedAllowedComponentsFromRenderExtension = + T extends RunnableExtension ? Components : never; + +/** + * For a given rendering extension target, returns the type of the API that the + * extension will receive at runtime. This API type is the second argument to + * the callback for that extension target. The first callback for all of the rendering + * extension targets each receive a `RemoteRoot` object. + */ +export type ApiForRenderExtension = + ExtractedApiFromRenderExtension; + +/** + * For a given rendering extension target, returns the UI components that the + * extension target supports. + */ +export type AllowedComponentsForRenderExtension< + ID extends keyof RenderExtensions, +> = ExtractedAllowedComponentsFromRenderExtension; diff --git a/packages/ui-extensions/src/surfaces/admin/shouldRender.ts b/packages/ui-extensions/src/surfaces/admin/shouldRender.ts new file mode 100644 index 000000000..041f1b859 --- /dev/null +++ b/packages/ui-extensions/src/surfaces/admin/shouldRender.ts @@ -0,0 +1,6 @@ +import {createShouldRenderRegistrationFunction} from '../../utilities/shouldRenderRegistration'; + +import type {ExtensionTargets} from './should-render-targets'; + +export const shouldRender = + createShouldRenderRegistrationFunction(); diff --git a/packages/ui-extensions/src/utilities/shouldRenderRegistration.ts b/packages/ui-extensions/src/utilities/shouldRenderRegistration.ts new file mode 100644 index 000000000..c7124b357 --- /dev/null +++ b/packages/ui-extensions/src/utilities/shouldRenderRegistration.ts @@ -0,0 +1,20 @@ +export interface ShouldRenderRegistrationFunction { + ( + target: Target, + callback: ExtensionPoints[Target], + ): ExtensionPoints[Target]; +} + +export function createShouldRenderRegistrationFunction< + ExtensionPoints, +>(): ShouldRenderRegistrationFunction { + const extensionWrapper: ShouldRenderRegistrationFunction = ( + target, + callback, + ) => { + (globalThis as any).shopify?.run(target, callback); + return callback; + }; + + return extensionWrapper; +}