Add returned types for event targets (#2694)

* fix versions link.

* update BaseTransactionComplete to use existing type.

* update docs and examples for event targets.

* add changeset

Author: fatbattk

.changeset/clean-keys-move.md

@@ -0,0 +1,5 @@
+---
+'@shopify/ui-extensions': patch
+---
+
+Update `BaseTransactionComplete.customer` to use existing type. Update examples and screenshots.

packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/POSReceiptBlock.doc.ts

@@ -13,29 +13,30 @@ const data: ReferenceEntityTemplateSchema = {
   > This component only accepts \`Text\` and \`QRCode\` components as children.`,
   isVisualComponent: true,
   type: 'component',
-  // eslint-disable-next-line no-warning-comments
-  // TODO: add images (and update description, examples, types, related) after determining what child components are allowed.
-  // thumbnail: 'pos-receipt-block-thumbnail.png',
-  // definitions: [
-  //   {
-  //     title: 'POSReceiptBlock',
-  //     description: '',
-  //     type: 'POSReceiptBlockProps',
-  //   },
-  // ],
+  thumbnail: 'pos-receipt-block-thumbnail.png',
   category: 'Components',
   related: [
     {
       name: 'Text',
+      subtitle: 'Acceptable child components',
+      type: 'apps',
       url: '/docs/api/pos-ui-extensions/components/text',
     },
     {
       name: 'QRCode',
+      subtitle: 'Acceptable child components',
+      type: 'apps',
       url: '/docs/api/pos-ui-extensions/components/qrcode',
     },
+    {
+      name: 'pos.receipt-footer.block.render',
+      subtitle: 'Target',
+      type: 'blocks',
+      url: '/docs/api/pos-ui-extensions/targets/receipts/pos-receipt-footer-block-render',
+    },
   ],
   defaultExample: {
-    // image: 'pos-receipt-block-default.png',
+    image: 'pos-receipt-block-default.png',
     codeblock: generateCodeBlockForPOSReceiptBlock(
       'Render a POSReceiptBlock in POS receipts',
       'default.example',

packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/QRCode.doc.ts

@@ -25,6 +25,7 @@ const data: ReferenceEntityTemplateSchema = {
     {
       name: 'POSReceiptBlock',
       subtitle: 'Required parent wrapper component',
+      type: 'apps',
       url: '/docs/api/pos-ui-extensions/components/posreceiptblock',
     },
   ],

packages/ui-extensions/docs/surfaces/point-of-sale/reference/examples/pos-receipt-block/default.example.ts

@@ -7,17 +7,19 @@ import {
 
 export default extension(
   'pos.receipt-footer.block.render',
-  (root) => {
+  (root, api) => {
     const block = root.createComponent(
       POSReceiptBlock,
     );
     const text = root.createComponent(
       Text,
       {},
-      'Submission ID: acde070d-8c2c-b0b0-9d8a-162843c10333',
+      'Custom receipt text',
     );
     const qrCode = root.createComponent(QRCode, {
-      value: 'https://www.shopify.com',
+      value: `https://www.shopify.com/?example=${encodeURIComponent(
+        api.transaction.orderId ?? '',
+      )}`,
     });
 
     block.append(text);

packages/ui-extensions/docs/surfaces/point-of-sale/reference/examples/pos-receipt-block/default.example.tsx

@@ -4,17 +4,25 @@ import {
   QRCode,
   Text,
   reactExtension,
+  useApi,
 } from '@shopify/ui-extensions-react/point-of-sale';
 
-const ReceiptFooterBlock = () => (
-  <POSReceiptBlock>
-    <Text>
-      Submission ID:
-      acde070d-8c2c-b0b0-9d8a-162843c10333
-    </Text>
-    <QRCode value="https://www.shopify.com" />
-  </POSReceiptBlock>
-);
+const ReceiptFooterBlock = () => {
+  const api = useApi(
+    'pos.receipt-footer.block.render',
+  );
+
+  return (
+    <POSReceiptBlock>
+      <Text>Custom receipt text</Text>
+      <QRCode
+        value={`https://www.shopify.com/?example=${encodeURIComponent(
+          api.transaction.orderId ?? '',
+        )}`}
+      />
+    </POSReceiptBlock>
+  );
+};
 
 export default reactExtension(
   'pos.receipt-footer.block.render',

packages/ui-extensions/docs/surfaces/point-of-sale/reference/examples/qrcode/default.example.ts

@@ -11,7 +11,7 @@ export default extension(
       POSReceiptBlock,
     );
     const qrCode = root.createComponent(QRCode, {
-      value: `https://example.com?id=${encodeURIComponent(
+      value: `https://shopify.com?example=${encodeURIComponent(
         api.transaction.orderId ?? '',
       )}`,
     });

packages/ui-extensions/docs/surfaces/point-of-sale/reference/examples/qrcode/default.example.tsx

@@ -14,7 +14,7 @@ const ReceiptFooterWithQRCodeBlock = () => {
   return (
     <POSReceiptBlock>
       <QRCode
-        value={`https://example.com?id=${encodeURIComponent(
+        value={`https://shopify.com?example=${encodeURIComponent(
           api.transaction.orderId ?? '',
         )}`}
       />

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

@@ -1,13 +1,35 @@
 import {
+  extension,
   POSReceiptBlock,
+  QRCode,
   Text,
-  extension,
 } from '@shopify/ui-extensions/point-of-sale';
 
 export default extension('pos.receipt-footer.block.render', (root, api) => {
   const block = root.createComponent(POSReceiptBlock);
-  const text = root.createComponent(Text, {}, `Order ID: ${api.order.id}`);
+  const textTransactionType = root.createComponent(
+    Text,
+    {},
+    `Transaction type: ${api.transaction.transactionType}`,
+  );
+  const textTaxTotal = root.createComponent(
+    Text,
+    {},
+    `Total tax: ${api.transaction.taxTotal}`,
+  );
+  const qrCodeValue =
+    api.transaction.transactionType === 'Exchange'
+      ? `exampleExchange=${encodeURIComponent(
+          api.transaction.exchangeId ?? '',
+        )}`
+      : `exampleOrder=${encodeURIComponent(api.transaction.orderId ?? '')}`;
+
+  const qrCode = root.createComponent(QRCode, {
+    value: `https://www.shopify.com?${qrCodeValue}`,
+  });
 
-  block.append(text);
+  block.append(textTransactionType);
+  block.append(textTaxTotal);
+  block.append(qrCode);
   root.append(block);
 });

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

@@ -1,17 +1,25 @@
 import React from 'react';
 
 import {
-  Text,
-  useApi,
   reactExtension,
+  useApi,
   POSReceiptBlock,
+  QRCode,
+  Text,
 } from '@shopify/ui-extensions-react/point-of-sale';
 
 const Block = () => {
-  const api = useApi<'pos.receipt-footer.block.render'>();
+  const {transaction} = useApi<'pos.receipt-footer.block.render'>();
+  const qrCodeValue =
+    transaction.transactionType === 'Exchange'
+      ? `exampleExchange=${encodeURIComponent(transaction.exchangeId ?? '')}`
+      : `exampleOrder=${encodeURIComponent(transaction.orderId ?? '')}`;
+
   return (
     <POSReceiptBlock>
-      <Text>{`Order ID: ${api.order.id}`}</Text>
+      <Text>{`Transaction type: ${transaction.transactionType}`}</Text>
+      <Text>{`Total tax: ${transaction.taxTotal}`}</Text>
+      <QRCode value={`https://www.shopify.com?${qrCodeValue}`} />
     </POSReceiptBlock>
   );
 };

packages/ui-extensions/docs/surfaces/point-of-sale/reference/helpers/helper.docs.ts

@@ -0,0 +1,11 @@
+// for use with `definitions` in a reference entity schema.
+export const CUSTOM_DATA = (type: string, title?: string) => ({
+  title: title ?? type,
+  description: 'The data object provided to this extension target.',
+  // exact type name auto-populates the properties.
+  type,
+});
+
+export const TRANSACTION_COMPLETE_DEFINITION = {
+  definitions: [CUSTOM_DATA('TransactionCompleteData')],
+};