Merge pull request #1955 from Shopify/js-cart-api-docs

Added examples for all cart functions

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

@@ -1,4 +1,9 @@
 import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+import {generateCodeBlock} from '../helpers/generateCodeBlock';
+
+const functionality = 'cart-api';
+const generateCodeBlockForCartApi = (title: string, fileName: string) =>
+  generateCodeBlock(title, functionality, fileName);
 
 const data: ReferenceEntityTemplateSchema = {
   name: 'Cart API',
@@ -15,6 +20,149 @@ const data: ReferenceEntityTemplateSchema = {
   ],
   category: 'APIs',
   related: [],
+  examples: {
+    description: 'Examples of using the Cart API',
+    examples: [
+      {
+        codeblock: generateCodeBlockForCartApi(
+          'Subscribe to cart changes.',
+          'subscribable',
+        ),
+      },
+      {
+        codeblock: generateCodeBlockForCartApi(
+          'Apply a cart level discount',
+          'apply-cart-discount',
+        ),
+      },
+      {
+        codeblock: generateCodeBlockForCartApi(
+          'Apply a cart level discount code',
+          'apply-cart-code-discount',
+        ),
+      },
+      {
+        codeblock: generateCodeBlockForCartApi(
+          'Remove all the discounts on the cart and line items',
+          'remove-all-discounts',
+        ),
+      },
+      {
+        codeblock: generateCodeBlockForCartApi(
+          'Set a custom discount on a line item',
+          'set-line-item-discount',
+        ),
+      },
+      {
+        codeblock: generateCodeBlockForCartApi(
+          'Set a custom discount on multiple line items',
+          'bulk-set-line-item-discounts',
+        ),
+      },
+      {
+        codeblock: generateCodeBlockForCartApi(
+          'Remove a discount on a line item',
+          'remove-line-item-discount',
+        ),
+      },
+      {
+        codeblock: generateCodeBlockForCartApi(
+          'Clear the entire cart',
+          'clear-cart',
+        ),
+      },
+      {
+        codeblock: generateCodeBlockForCartApi(
+          'Set the customer in the cart',
+          'set-customer',
+        ),
+      },
+      {
+        codeblock: generateCodeBlockForCartApi(
+          'Remove the customer in the cart',
+          'remove-customer',
+        ),
+      },
+      {
+        codeblock: generateCodeBlockForCartApi(
+          'Add a custom sale to the cart',
+          'add-custom-sale',
+        ),
+      },
+      {
+        codeblock: generateCodeBlockForCartApi(
+          'Add a line item to the cart',
+          'add-line-item',
+        ),
+      },
+      {
+        codeblock: generateCodeBlockForCartApi(
+          'Remove a line item from the cart',
+          'remove-line-item',
+        ),
+      },
+      {
+        codeblock: generateCodeBlockForCartApi(
+          'Add custom properties to the cart',
+          'add-cart-properties',
+        ),
+      },
+      {
+        codeblock: generateCodeBlockForCartApi(
+          'Remove custom properties from the cart',
+          'remove-cart-properties',
+        ),
+      },
+      {
+        codeblock: generateCodeBlockForCartApi(
+          'Add custom properties to a line item',
+          'add-line-item-properties',
+        ),
+      },
+      {
+        codeblock: generateCodeBlockForCartApi(
+          'Add custom properties to multiple line items',
+          'bulk-add-line-item-properties',
+        ),
+      },
+      {
+        codeblock: generateCodeBlockForCartApi(
+          'Remove custom properties from a line item',
+          'remove-line-item-properties',
+        ),
+      },
+      {
+        codeblock: generateCodeBlockForCartApi(
+          'Set an attributed staff member on the cart',
+          'set-attributed-staff',
+        ),
+      },
+      {
+        codeblock: generateCodeBlockForCartApi(
+          'Set an attributed staff member on a line item',
+          'set-attributed-staff-to-line-item',
+        ),
+      },
+      {
+        codeblock: generateCodeBlockForCartApi(
+          'Add an address to the customer in the cart',
+          'add-address',
+        ),
+      },
+      {
+        codeblock: generateCodeBlockForCartApi(
+          'Delete an address corresponding to an ID',
+          'delete-address',
+        ),
+      },
+      {
+        codeblock: generateCodeBlockForCartApi(
+          'Set the default address of the customer in the cart',
+          'update-default-address',
+        ),
+      },
+    ],
+  },
 };
 
 export default data;

packages/ui-extensions/docs/surfaces/point-of-sale/reference/examples/action-api/present-modal.ts

@@ -5,27 +5,23 @@ import {
   extension,
 } from '@shopify/ui-extensions/point-of-sale';
 
-export default extension(
-  'pos.purchase.post.action.render',
-  (root, api) => {
-    const button = root.createComponent(Button, {
-      onPress: () => {
-        console.log('Button pressed');
-      },
-      title: 'Button test',
-    });
+export default extension('pos.purchase.post.action.render', (root, api) => {
+  const button = root.createComponent(Button, {
+    onPress: () => {
+      api.action.presentModal();
+    },
+    title: 'Button test',
+  });
 
-    const screen = root.createComponent(Screen, {
-      title: 'Post-Purchase Title',
-      name: 'Post-Purchase Name',
-    });
+  const screen = root.createComponent(Screen, {
+    title: 'Post-Purchase Title',
+    name: 'Post-Purchase Name',
+  });
 
-    screen.append(button);
+  screen.append(button);
 
-    const navigator =
-      root.createComponent(Navigator);
-    navigator.append(screen);
+  const navigator = root.createComponent(Navigator);
+  navigator.append(screen);
 
-    root.append(navigator);
-  },
-);
+  root.append(navigator);
+});

packages/ui-extensions/docs/surfaces/point-of-sale/reference/examples/cart-api/add-address.ts

@@ -0,0 +1,21 @@
+import {Tile, extension} from '@shopify/ui-extensions/point-of-sale';
+
+export default extension('pos.home.tile.render', (root, api) => {
+  const tile = root.createComponent(Tile, {
+    title: 'My App',
+    subtitle: 'Call cart function',
+    enabled: true,
+    onPress: () => {
+      api.cart.addAddress({
+        address1: '123456 Main Street',
+        city: 'Ottawa',
+        province: 'Ontario',
+        firstName: 'John',
+        lastName: 'Doe',
+        country: 'Canada',
+      });
+    },
+  });
+
+  root.append(tile);
+});

packages/ui-extensions/docs/surfaces/point-of-sale/reference/examples/cart-api/add-address.tsx

@@ -0,0 +1,32 @@
+
+import React from 'react';
+import {
+  reactExtension,
+  useApi,
+  Tile
+} from '@shopify/ui-extensions-react/point-of-sale';
+
+const SmartGridTile = () => {
+  const api = useApi<'pos.home.tile.render'>();
+
+  return (
+    <Tile 
+      title="My App" 
+      subtitle='Call cart function' 
+      enabled 
+      onPress={() => api.cart.addAddress({
+        address1: '123456 Main Street', 
+        city: 'Ottawa', 
+        province: 'Ontario',
+        firstName: 'John',
+        lastName: 'Doe',
+        country: 'Canada'
+      })}
+    />
+  );
+};
+
+export default reactExtension(
+  'pos.home.tile.render',
+  () => <SmartGridTile />
+);

packages/ui-extensions/docs/surfaces/point-of-sale/reference/examples/cart-api/add-cart-properties.ts

@@ -0,0 +1,14 @@
+import {Tile, extension} from '@shopify/ui-extensions/point-of-sale';
+
+export default extension('pos.home.tile.render', (root, api) => {
+  const tile = root.createComponent(Tile, {
+    title: 'My App',
+    subtitle: 'Call cart action',
+    enabled: true,
+    onPress: () => {
+      api.cart.addCartProperties({Engraving: 'John Doe'});
+    },
+  });
+
+  root.append(tile);
+});

packages/ui-extensions/docs/surfaces/point-of-sale/reference/examples/cart-api/add-cart-properties.tsx

@@ -0,0 +1,25 @@
+
+import React from 'react';
+import {
+  reactExtension,
+  useApi,
+  Tile
+} from '@shopify/ui-extensions-react/point-of-sale';
+
+const SmartGridTile = () => {
+  const api = useApi<'pos.home.tile.render'>();
+
+  return (
+    <Tile 
+      title="My App" 
+      subtitle='Call cart function' 
+      enabled 
+      onPress={() => api.cart.addCartProperties({Engraving: 'John Doe'})}
+    />
+  );
+};
+
+export default reactExtension(
+  'pos.home.tile.render',
+  () => <SmartGridTile />
+);

packages/ui-extensions/docs/surfaces/point-of-sale/reference/examples/cart-api/add-custom-sale.ts

@@ -0,0 +1,19 @@
+import {Tile, extension} from '@shopify/ui-extensions/point-of-sale';
+
+export default extension('pos.home.tile.render', (root, api) => {
+  const tile = root.createComponent(Tile, {
+    title: 'My App',
+    subtitle: 'Call cart function',
+    enabled: true,
+    onPress: () => {
+      api.cart.addCustomSale({
+        title: 'New product',
+        quantity: 1,
+        price: '10.00',
+        taxable: true,
+      });
+    },
+  });
+
+  root.append(tile);
+});

packages/ui-extensions/docs/surfaces/point-of-sale/reference/examples/cart-api/add-custom-sale.tsx

@@ -0,0 +1,30 @@
+
+import React from 'react';
+import {
+  reactExtension,
+  useApi,
+  Tile
+} from '@shopify/ui-extensions-react/point-of-sale';
+
+const SmartGridTile = () => {
+  const api = useApi<'pos.home.tile.render'>();
+
+  return (
+    <Tile 
+      title="My App" 
+      subtitle='Call cart function' 
+      enabled 
+      onPress={() => api.cart.addCustomSale({
+        title: 'New product',
+        quantity: 1,
+        price: '10.00',
+        taxable: true,
+      })}
+    />
+  );
+};
+
+export default reactExtension(
+  'pos.home.tile.render',
+  () => <SmartGridTile />
+);

packages/ui-extensions/docs/surfaces/point-of-sale/reference/examples/cart-api/add-line-item-properties.ts

@@ -0,0 +1,14 @@
+import {Tile, extension} from '@shopify/ui-extensions/point-of-sale';
+
+export default extension('pos.home.tile.render', (root, api) => {
+  const tile = root.createComponent(Tile, {
+    title: 'My App',
+    subtitle: 'Call cart function',
+    enabled: true,
+    onPress: () => {
+      api.cart.addLineItemProperties('aa-1234567', {Engraving: 'John Doe'});
+    },
+  });
+
+  root.append(tile);
+});

packages/ui-extensions/docs/surfaces/point-of-sale/reference/examples/cart-api/add-line-item-properties.tsx

@@ -0,0 +1,25 @@
+
+import React from 'react';
+import {
+  reactExtension,
+  useApi,
+  Tile
+} from '@shopify/ui-extensions-react/point-of-sale';
+
+const SmartGridTile = () => {
+  const api = useApi<'pos.home.tile.render'>();
+
+  return (
+    <Tile 
+      title="My App" 
+      subtitle='Call cart function' 
+      enabled 
+      onPress={() => api.cart.addLineItemProperties('aa-1234567', {Engraving: 'John Doe'})}
+    />
+  );
+};
+
+export default reactExtension(
+  'pos.home.tile.render',
+  () => <SmartGridTile />
+);