Add order-api examples

Author: NathanJolly

packages/ui-extensions-react/src/surfaces/point-of-sale/hooks/index.ts

@@ -14,6 +14,7 @@ export {
   useStatefulSubscribableLocale,
   destroyStatefulSubscribableLocale,
 } from './locale-api';
+export {useOrder} from './order-api';
 
 export {
   useScannerDataSubscription,

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

@@ -1,6 +1,10 @@
 import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+import {generateCodeBlock} from '../helpers/generateCodeBlock';
 import {ExtensionTargetType, TargetLink} from '../types/ExtensionTargetType';
 
+const generateCodeBlockForOrderApi = (title: string, fileName: string) =>
+  generateCodeBlock(title, 'order-api', fileName);
+
 const data: ReferenceEntityTemplateSchema = {
   name: 'Order API',
   description: `
@@ -25,6 +29,35 @@ The Order API provides an extension with data about the current order.
   ],
   category: 'APIs',
   related: [],
+  examples: {
+    description: 'Examples of using the Order API',
+    examples: [
+      {
+        codeblock: generateCodeBlockForOrderApi(
+          'Basic usage of the Order API with useOrder hook',
+          'basic-usage',
+        ),
+      },
+      {
+        codeblock: generateCodeBlockForOrderApi(
+          'Display order details in a custom block',
+          'display-in-block',
+        ),
+      },
+      {
+        codeblock: generateCodeBlockForOrderApi(
+          'Use Order API with navigation',
+          'with-navigation',
+        ),
+      },
+      {
+        codeblock: generateCodeBlockForOrderApi(
+          'Simple useOrder hook example',
+          'use-order-hook',
+        ),
+      },
+    ],
+  },
 };
 
 export default data;

packages/ui-extensions/docs/surfaces/point-of-sale/reference/examples/order-api/basic-usage.ts

@@ -0,0 +1,32 @@
+import {
+  extension,
+  Screen,
+  Navigator,
+  ScrollView,
+  Text,
+  Section,
+} from '@shopify/ui-extensions/point-of-sale';
+
+export default extension('pos.purchase.post.block.render', (root, api) => {
+  // Access order information from the API
+  const order = api.order;
+
+  const navigator = root.createComponent(Navigator, {});
+  const screen = navigator.createComponent(Screen, {
+    name: 'OrderDetails',
+    title: 'Order Details',
+  });
+  const scrollView = screen.createComponent(ScrollView, {});
+  const section = scrollView.createComponent(Section, {
+    title: 'Order Information',
+  });
+
+  section.createComponent(Text, {}, `Order ID: ${order.id}`);
+  section.createComponent(Text, {}, `Order Name: ${order.name}`);
+
+  if (order.customerId) {
+    section.createComponent(Text, {}, `Customer ID: ${order.customerId}`);
+  }
+
+  root.mount();
+});

packages/ui-extensions/docs/surfaces/point-of-sale/reference/examples/order-api/basic-usage.tsx

@@ -0,0 +1,33 @@
+import React from 'react';
+import {
+  reactExtension,
+  Screen,
+  Navigator,
+  ScrollView,
+  Text,
+  Section,
+  useOrder,
+} from '@shopify/ui-extensions-react/point-of-sale';
+
+const SmartGridModal = () => {
+  // Use the useOrder hook to access order information
+  const order = useOrder();
+
+  return (
+    <Navigator>
+      <Screen name="OrderDetails" title="Order Details">
+        <ScrollView>
+          <Section title="Order Information">
+            <Text>Order ID: {order.id}</Text>
+            <Text>Order Name: {order.name}</Text>
+            {order.customerId && <Text>Customer ID: {order.customerId}</Text>}
+          </Section>
+        </ScrollView>
+      </Screen>
+    </Navigator>
+  );
+};
+
+export default reactExtension('pos.purchase.post.block.render', () => (
+  <SmartGridModal />
+));

packages/ui-extensions/docs/surfaces/point-of-sale/reference/examples/order-api/display-in-block.ts

@@ -0,0 +1,30 @@
+import {
+  extension,
+  POSBlock,
+  POSBlockRow,
+} from '@shopify/ui-extensions/point-of-sale';
+
+export default extension('pos.order-details.block.render', (root, api) => {
+  const order = api.order;
+
+  const posBlock = root.createComponent(POSBlock, {});
+
+  posBlock.createComponent(POSBlockRow, {
+    label: 'Order',
+    value: order.name,
+  });
+
+  posBlock.createComponent(POSBlockRow, {
+    label: 'Order ID',
+    value: order.id.toString(),
+  });
+
+  if (order.customerId) {
+    posBlock.createComponent(POSBlockRow, {
+      label: 'Customer ID',
+      value: order.customerId.toString(),
+    });
+  }
+
+  root.mount();
+});

packages/ui-extensions/docs/surfaces/point-of-sale/reference/examples/order-api/display-in-block.tsx

@@ -0,0 +1,26 @@
+import React from 'react';
+import {
+  reactExtension,
+  POSBlock,
+  POSBlockRow,
+  useOrder,
+} from '@shopify/ui-extensions-react/point-of-sale';
+
+const OrderDetailsBlock = () => {
+  // Use the useOrder hook directly
+  const order = useOrder();
+
+  return (
+    <POSBlock>
+      <POSBlockRow label="Order" value={order.name} />
+      <POSBlockRow label="Order ID" value={order.id.toString()} />
+      {order.customerId && (
+        <POSBlockRow label="Customer ID" value={order.customerId.toString()} />
+      )}
+    </POSBlock>
+  );
+};
+
+export default reactExtension('pos.order-details.block.render', () => (
+  <OrderDetailsBlock />
+));

packages/ui-extensions/docs/surfaces/point-of-sale/reference/examples/order-api/use-order-hook.ts

@@ -0,0 +1,17 @@
+import {extension, Text, Stack} from '@shopify/ui-extensions/point-of-sale';
+
+export default extension('pos.order-details.block.render', (root, api) => {
+  // Access order data directly from the API
+  const order = api.order;
+
+  const stack = root.createComponent(Stack, {});
+
+  stack.createComponent(Text, {}, `Order #${order.name}`);
+  stack.createComponent(Text, {}, `ID: ${order.id}`);
+
+  if (order.customerId) {
+    stack.createComponent(Text, {}, `Customer ID: ${order.customerId}`);
+  }
+
+  root.mount();
+});

packages/ui-extensions/docs/surfaces/point-of-sale/reference/examples/order-api/use-order-hook.tsx

@@ -0,0 +1,24 @@
+import React from 'react';
+import {
+  reactExtension,
+  Text,
+  Stack,
+  useOrder,
+} from '@shopify/ui-extensions-react/point-of-sale';
+
+const OrderInfo = () => {
+  // The useOrder hook provides direct access to order data
+  const order = useOrder();
+
+  return (
+    <Stack>
+      <Text>Order #{order.name}</Text>
+      <Text>ID: {order.id}</Text>
+      {order.customerId && <Text>Customer ID: {order.customerId}</Text>}
+    </Stack>
+  );
+};
+
+export default reactExtension('pos.order-details.block.render', () => (
+  <OrderInfo />
+));

packages/ui-extensions/docs/surfaces/point-of-sale/reference/examples/order-api/with-navigation.ts

@@ -0,0 +1,33 @@
+import {
+  extension,
+  Navigator,
+  Screen,
+  Text,
+  Button,
+} from '@shopify/ui-extensions/point-of-sale';
+
+export default extension('pos.purchase.post.action.render', (root, api) => {
+  const order = api.order;
+  const navigation = api.navigation;
+
+  const navigator = root.createComponent(Navigator, {});
+  const screen = navigator.createComponent(Screen, {
+    name: 'OrderActions',
+    title: 'Order Actions',
+  });
+
+  screen.createComponent(Text, {}, `Processing order: ${order.name}`);
+
+  if (order.customerId) {
+    screen.createComponent(Button, {
+      title: 'View Customer',
+      onPress: () => {
+        navigation.navigate('CustomerDetails', {
+          customerId: order.customerId,
+        });
+      },
+    });
+  }
+
+  root.mount();
+});

packages/ui-extensions/docs/surfaces/point-of-sale/reference/examples/order-api/with-navigation.tsx

@@ -0,0 +1,39 @@
+import React from 'react';
+import {
+  reactExtension,
+  Navigator,
+  Screen,
+  Text,
+  Button,
+  useOrder,
+  useApi,
+} from '@shopify/ui-extensions-react/point-of-sale';
+
+const OrderActionModal = () => {
+  const order = useOrder();
+  const {navigation} = useApi();
+
+  const handleViewCustomer = () => {
+    if (order.customerId) {
+      // Navigate to customer details
+      navigation.navigate('CustomerDetails', {
+        customerId: order.customerId,
+      });
+    }
+  };
+
+  return (
+    <Navigator>
+      <Screen name="OrderActions" title="Order Actions">
+        <Text>Processing order: {order.name}</Text>
+        {order.customerId && (
+          <Button title="View Customer" onPress={handleViewCustomer} />
+        )}
+      </Screen>
+    </Navigator>
+  );
+};
+
+export default reactExtension('pos.purchase.post.action.render', () => (
+  <OrderActionModal />
+));