add drawer extension targets

.changeset/drawer-details-extension-targets.md

@@ -0,0 +1,5 @@
+---
+'@shopify/ui-extensions': minor
+---
+
+Introduce drawer details extension targets

packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/drawer-api.doc.ts

@@ -0,0 +1,55 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+import {ExtensionTargetType, TargetLink} from '../types/ExtensionTargetType';
+import {generateCodeBlock} from '../helpers/generateCodeBlock';
+
+const generateCodeBlockForDrawerApi = (title: string, fileName: string) =>
+  generateCodeBlock(title, 'drawer-api', fileName);
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'Drawer API',
+  description: `
+The Drawer API provides an extension with data about the current drawer/cash tracking session.
+
+#### Supporting targets
+- ${TargetLink.PosDrawerDetailsActionMenuItemRender}
+- ${TargetLink.PosDrawerDetailsActionRender}
+- ${TargetLink.PosDrawerDetailsBlockRender}
+`,
+  isVisualComponent: false,
+  type: 'APIs',
+  definitions: [
+    {
+      title: 'DrawerApi',
+      description: '',
+      type: 'DrawerApi',
+    },
+  ],
+  examples: {
+    description: 'Examples of using the Drawer API.',
+    examples: [
+      {
+        codeblock: generateCodeBlockForDrawerApi(
+          'Retrieve the ID of the drawer.',
+          'id',
+        ),
+      },
+    ],
+  },
+  category: 'APIs',
+  related: [
+    {
+      name: ExtensionTargetType.PosDrawerDetailsActionMenuItemRender,
+      url: '/docs/api/pos-ui-extensions/targets/pos-drawer-details-action-menu-item-render',
+    },
+    {
+      name: ExtensionTargetType.PosDrawerDetailsActionRender,
+      url: '/docs/api/pos-ui-extensions/targets/pos-drawer-details-action-render',
+    },
+    {
+      name: ExtensionTargetType.PosDrawerDetailsBlockRender,
+      url: '/docs/api/pos-ui-extensions/targets/pos-drawer-details-block-render',
+    },
+  ],
+};
+
+export default data;

packages/ui-extensions/docs/surfaces/point-of-sale/reference/examples/drawer-api/id.ts

@@ -0,0 +1,23 @@
+import {
+  Navigator,
+  Screen,
+  ScrollView,
+  Text,
+  extension,
+} from '@shopify/ui-extensions/point-of-sale';
+
+export default extension('pos.drawer-details.action.render', (root, api) => {
+  const navigator = root.createComponent(Navigator);
+  const screen = root.createComponent(Screen, {
+    name: 'DrawerApi',
+    title: 'Drawer Api',
+  });
+  const scrollView = root.createComponent(ScrollView);
+  const text = root.createComponent(Text);
+
+  text.append(`Drawer ID: ${api.drawer.id}`);
+  scrollView.append(text);
+  screen.append(scrollView);
+  navigator.append(screen);
+  root.append(navigator);
+});

packages/ui-extensions/docs/surfaces/point-of-sale/reference/examples/drawer-api/id.tsx

@@ -0,0 +1,27 @@
+import React from 'react';
+
+import {
+  Text,
+  Screen,
+  ScrollView,
+  Navigator,
+  reactExtension,
+  useApi,
+} from '@shopify/ui-extensions-react/point-of-sale';
+
+const Modal = () => {
+  const api = useApi<'pos.drawer-details.action.render'>();
+  return (
+    <Navigator>
+      <Screen name="DrawerApi" title="Drawer Api">
+        <ScrollView>
+          <Text>{`Drawer ID: ${api.drawer.id}`}</Text>
+        </ScrollView>
+      </Screen>
+    </Navigator>
+  );
+};
+
+export default reactExtension('pos.drawer-details.action.render', () => (
+  <Modal />
+));

packages/ui-extensions/docs/surfaces/point-of-sale/reference/examples/targets/pos-drawer-details-action-menu-item-render.ts

@@ -0,0 +1,14 @@
+import {Button, extension} from '@shopify/ui-extensions/point-of-sale';
+
+export default extension(
+  'pos.drawer-details.action.menu-item.render',
+  (root, api) => {
+    const button = root.createComponent(Button, {
+      onPress: () => {
+        api.action.presentModal();
+      },
+    });
+
+    root.append(button);
+  },
+);

packages/ui-extensions/docs/surfaces/point-of-sale/reference/examples/targets/pos-drawer-details-action-menu-item-render.tsx

@@ -0,0 +1,17 @@
+import React from 'react';
+import {
+  reactExtension,
+  Button,
+  useApi,
+} from '@shopify/ui-extensions-react/point-of-sale';
+
+const ButtonComponent = () => {
+  const api = useApi<'pos.drawer-details.action.menu-item.render'>();
+
+  return <Button onPress={() => api.action.presentModal()} />;
+};
+
+export default reactExtension(
+  'pos.drawer-details.action.menu-item.render',
+  () => <ButtonComponent />,
+);

packages/ui-extensions/docs/surfaces/point-of-sale/reference/examples/targets/pos-drawer-details-action-render.ts

@@ -0,0 +1,23 @@
+import {
+  Navigator,
+  Screen,
+  ScrollView,
+  Text,
+  extension,
+} from '@shopify/ui-extensions/point-of-sale';
+
+export default extension('pos.drawer-details.action.render', (root, api) => {
+  const navigator = root.createComponent(Navigator);
+  const screen = root.createComponent(Screen, {
+    name: 'DrawerDetails',
+    title: 'Drawer Details',
+  });
+  const scrollView = root.createComponent(ScrollView);
+  const text = root.createComponent(Text);
+
+  text.append(`Drawer ID: ${api.drawer.id}`);
+  scrollView.append(text);
+  screen.append(scrollView);
+  navigator.append(screen);
+  root.append(navigator);
+});

packages/ui-extensions/docs/surfaces/point-of-sale/reference/examples/targets/pos-drawer-details-action-render.tsx

@@ -0,0 +1,27 @@
+import React from 'react';
+
+import {
+  Text,
+  Screen,
+  ScrollView,
+  Navigator,
+  reactExtension,
+  useApi,
+} from '@shopify/ui-extensions-react/point-of-sale';
+
+const Modal = () => {
+  const api = useApi<'pos.drawer-details.action.render'>();
+  return (
+    <Navigator>
+      <Screen name="DrawerDetails" title="Drawer Details">
+        <ScrollView>
+          <Text>{`Drawer ID: ${api.drawer.id}`}</Text>
+        </ScrollView>
+      </Screen>
+    </Navigator>
+  );
+};
+
+export default reactExtension('pos.drawer-details.action.render', () => (
+  <Modal />
+));

packages/ui-extensions/docs/surfaces/point-of-sale/reference/examples/targets/pos-drawer-details-block-render.ts

@@ -0,0 +1,28 @@
+import {
+  POSBlock,
+  Text,
+  POSBlockRow,
+  extension,
+} from '@shopify/ui-extensions/point-of-sale';
+
+export default extension('pos.drawer-details.block.render', (root, api) => {
+  const block = root.createComponent(POSBlock, {
+    action: {title: 'Open action', onPress: api.action.presentModal},
+  });
+
+  const mainText = root.createComponent(Text);
+  mainText.append('This is a drawer details block extension');
+
+  const subtitleText = root.createComponent(Text);
+  subtitleText.append(`Drawer ID: ${api.drawer.id}`);
+
+  const blockMainRow = root.createComponent(POSBlockRow);
+  blockMainRow.append(mainText);
+
+  const blockSubtitleRow = root.createComponent(POSBlockRow);
+  blockSubtitleRow.append(subtitleText);
+  block.append(blockMainRow);
+  block.append(blockSubtitleRow);
+
+  root.append(block);
+});

packages/ui-extensions/docs/surfaces/point-of-sale/reference/examples/targets/pos-drawer-details-block-render.tsx

@@ -0,0 +1,27 @@
+import React from 'react';
+
+import {
+  Text,
+  useApi,
+  reactExtension,
+  POSBlock,
+  POSBlockRow,
+} from '@shopify/ui-extensions-react/point-of-sale';
+
+const Block = () => {
+  const api = useApi<'pos.drawer-details.block.render'>();
+  return (
+    <POSBlock action={{title: 'Open action', onPress: api.action.presentModal}}>
+      <POSBlockRow>
+        <Text>This is a drawer details block extension</Text>
+      </POSBlockRow>
+      <POSBlockRow>
+        <Text>{`Drawer ID: ${api.drawer.id}`}</Text>
+      </POSBlockRow>
+    </POSBlock>
+  );
+};
+
+export default reactExtension('pos.drawer-details.block.render', () => (
+  <Block />
+));

packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.drawer-details.action.menu-item.render.doc.ts

@@ -0,0 +1,32 @@
+import type {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+import {generateCodeBlock} from '../helpers/generateCodeBlock';
+import {ExtensionTargetType} from '../types/ExtensionTargetType';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: ExtensionTargetType.PosDrawerDetailsActionMenuItemRender,
+  description:
+    'A static extension target that renders as a menu item on the drawer details screen',
+  defaultExample: {
+    codeblock: generateCodeBlock(
+      'Drawer details action menu item',
+      'targets',
+      'pos-drawer-details-action-menu-item-render',
+    ),
+  },
+  category: 'Targets',
+  subCategory: 'Drawer details',
+  isVisualComponent: false,
+  related: [
+    {
+      name: ExtensionTargetType.PosDrawerDetailsActionRender,
+      url: '/docs/api/pos-ui-extensions/targets/pos-drawer-details-action-render',
+    },
+    {
+      name: ExtensionTargetType.PosDrawerDetailsBlockRender,
+      url: '/docs/api/pos-ui-extensions/targets/pos-drawer-details-block-render',
+    },
+  ],
+  type: 'Target',
+};
+
+export default data;

packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.drawer-details.action.render.doc.ts

@@ -0,0 +1,32 @@
+import type {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+import {generateCodeBlock} from '../helpers/generateCodeBlock';
+import {ExtensionTargetType} from '../types/ExtensionTargetType';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: ExtensionTargetType.PosDrawerDetailsActionRender,
+  description:
+    'A full-screen extension target that renders when a `pos.drawer-details.action.menu-item.render` target calls for it',
+  defaultExample: {
+    codeblock: generateCodeBlock(
+      'Drawer details action',
+      'targets',
+      'pos-drawer-details-action-render',
+    ),
+  },
+  category: 'Targets',
+  subCategory: 'Drawer details',
+  isVisualComponent: false,
+  related: [
+    {
+      name: ExtensionTargetType.PosDrawerDetailsActionMenuItemRender,
+      url: '/docs/api/pos-ui-extensions/targets/pos-drawer-details-action-menu-item-render',
+    },
+    {
+      name: ExtensionTargetType.PosDrawerDetailsBlockRender,
+      url: '/docs/api/pos-ui-extensions/targets/pos-drawer-details-block-render',
+    },
+  ],
+  type: 'Target',
+};
+
+export default data;

packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.drawer-details.block.render.doc.ts

@@ -0,0 +1,32 @@
+import type {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+import {generateCodeBlock} from '../helpers/generateCodeBlock';
+import {ExtensionTargetType} from '../types/ExtensionTargetType';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: ExtensionTargetType.PosDrawerDetailsBlockRender,
+  description:
+    'Renders a custom section within the native drawer details screen',
+  defaultExample: {
+    codeblock: generateCodeBlock(
+      'Block',
+      'targets',
+      'pos-drawer-details-block-render',
+    ),
+  },
+  category: 'Targets',
+  subCategory: 'Drawer details',
+  isVisualComponent: false,
+  related: [
+    {
+      name: ExtensionTargetType.PosDrawerDetailsActionMenuItemRender,
+      url: '/docs/api/pos-ui-extensions/targets/pos-drawer-details-action-menu-item-render',
+    },
+    {
+      name: ExtensionTargetType.PosDrawerDetailsActionRender,
+      url: '/docs/api/pos-ui-extensions/targets/pos-drawer-details-action-render',
+    },
+  ],
+  type: 'Target',
+};
+
+export default data;

packages/ui-extensions/docs/surfaces/point-of-sale/reference/types/ExtensionTargetType.ts

@@ -23,6 +23,10 @@ export enum ExtensionTargetType {
   PosReceiptFooterBlockRender = 'pos.receipt-footer.block.render',
   PosCartLineItemDetailsActionMenuItemRender = 'pos.cart.line-item-details.action.menu-item.render',
   PosCartLineItemDetailsActionRender = 'pos.cart.line-item-details.action.render',
+  PosCartLineItemDetailsBlockRender = 'pos.cart.line-item-details.block.render',
+  PosDrawerDetailsActionMenuItemRender = 'pos.drawer-details.action.menu-item.render',
+  PosDrawerDetailsActionRender = 'pos.drawer-details.action.render',
+  PosDrawerDetailsBlockRender = 'pos.drawer-details.block.render',
 }
 
 export enum TargetLink {
@@ -50,4 +54,8 @@ export enum TargetLink {
   PosReceiptFooterBlockRender = '[pos.receipt-footer.block.render](/docs/api/pos-ui-extensions/targets/receipts/pos-receipt-footer-block-render)',
   PosCartLineItemDetailsActionMenuItemRender = '[pos.cart.line-item-details.action.menu-item.render](/docs/api/pos-ui-extensions/targets/cart-details/pos-cart-line-item-details-action-menu-item-render)',
   PosCartLineItemDetailsActionRender = '[pos.cart.line-item-details.action.render](/docs/api/pos-ui-extensions/targets/cart-details/pos-cart-line-item-details-action-render)',
+  PosCartLineItemDetailsBlockRender = '[pos.cart.line-item-details.block.render](/docs/api/pos-ui-extensions/targets/cart-details/pos-cart-line-item-details-block-render)',
+  PosDrawerDetailsActionMenuItemRender = '[pos.drawer-details.action.menu-item.render](/docs/api/pos-ui-extensions/targets/drawer-details/pos-drawer-details-action-menu-item-render)',
+  PosDrawerDetailsActionRender = '[pos.drawer-details.action.render](/docs/api/pos-ui-extensions/targets/drawer-details/pos-drawer-details-action-render)',
+  PosDrawerDetailsBlockRender = '[pos.drawer-details.block.render](/docs/api/pos-ui-extensions/targets/drawer-details/pos-drawer-details-block-render)',
 }

packages/ui-extensions/src/surfaces/point-of-sale/api.ts

@@ -7,6 +7,8 @@ export type {
 
 export type {CartLineItemApi} from './render/api/cart-line-item-api/cart-line-item-api';
 
+export type {DrawerApi} from './render/api/drawer-api/drawer-api';
+
 export type {
   ActionApi,
   ActionApiContent,