[Checkout UI Ext] Checkout data API examples + descriptions

packages/ui-extensions/docs/surfaces/checkout/reference/apis/address.doc.ts

@@ -2,6 +2,7 @@ import type {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
 
 import {
   getLinksByTag,
+  getExample,
   STANDARD_API_PROPERTIES_DESCRIPTION,
   CHECKOUT_API_PROPERTIES_DESCRIPTION,
   REQUIRES_PROTECTED_CUSTOMER_DATA_LEVEL_2,
@@ -45,6 +46,11 @@ const data: ReferenceEntityTemplateSchema = {
       type: 'UseApplyShippingAddressChangeGeneratedType',
     },
   ],
+  defaultExample: getExample('address/shipping-address', ['jsx']),
+  examples: {
+    description: '',
+    examples: [getExample('address/billing-address', ['jsx'])],
+  },
   related: getLinksByTag('apis'),
 };
 

packages/ui-extensions/docs/surfaces/checkout/reference/apis/buyer-identity.doc.ts

@@ -3,6 +3,7 @@ import type {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
 import {
   STANDARD_API_PROPERTIES_DESCRIPTION,
   REQUIRES_PROTECTED_CUSTOMER_DATA_LEVEL_2,
+  getExample,
   getLinksByTag,
 } from '../helper.docs';
 
@@ -45,6 +46,11 @@ const data: ReferenceEntityTemplateSchema = {
       type: 'UsePurchasingCompanyGeneratedType',
     },
   ],
+  defaultExample: getExample('buyer-identity/customer-info', ['jsx']),
+  examples: {
+    description: '',
+    examples: [getExample('buyer-identity/purchasing-company', ['jsx'])],
+  },
   related: getLinksByTag('apis'),
 };
 

packages/ui-extensions/docs/surfaces/checkout/reference/apis/cart-lines.doc.ts

@@ -57,6 +57,10 @@ const data: ReferenceEntityTemplateSchema = {
     },
   ],
   defaultExample: getExample('cart-line-item/default', ['jsx']),
+  examples: {
+    description: '',
+    examples: [getExample('cart-lines/summary', ['jsx'])],
+  },
   related: getLinksByTag('apis'),
 };
 

packages/ui-extensions/docs/surfaces/checkout/reference/apis/checkout-token.doc.ts

@@ -2,6 +2,7 @@ import type {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
 
 import {
   getLinksByTag,
+  getExample,
   STANDARD_API_PROPERTIES_DESCRIPTION,
 } from '../helper.docs';
 
@@ -24,6 +25,11 @@ const data: ReferenceEntityTemplateSchema = {
       type: 'UseCheckoutTokenGeneratedType',
     },
   ],
+  defaultExample: getExample('checkout-token/default', ['jsx']),
+  examples: {
+    description: '',
+    examples: [getExample('checkout-token/support-message', ['jsx'])],
+  },
   related: getLinksByTag('apis'),
 };
 

packages/ui-extensions/docs/surfaces/checkout/reference/apis/cost.doc.ts

@@ -2,6 +2,7 @@ import type {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
 
 import {
   getLinksByTag,
+  getExample,
   STANDARD_API_PROPERTIES_DESCRIPTION,
 } from '../helper.docs';
 
@@ -43,6 +44,11 @@ const data: ReferenceEntityTemplateSchema = {
       type: 'UseTotalAmountGeneratedType',
     },
   ],
+  defaultExample: getExample('cost/order-summary', ['jsx']),
+  examples: {
+    description: '',
+    examples: [getExample('cost/free-shipping-goal', ['jsx'])],
+  },
   related: getLinksByTag('apis'),
 };
 

packages/ui-extensions/docs/surfaces/checkout/reference/apis/customer-privacy.doc.ts

@@ -32,6 +32,10 @@ const data: ReferenceEntityTemplateSchema = {
     },
   ],
   defaultExample: getExample('customer-privacy/default', ['jsx']),
+  examples: {
+    description: '',
+    examples: [getExample('customer-privacy/consent-banner', ['jsx'])],
+  },
   related: getLinksByTag('apis'),
 };
 

packages/ui-extensions/docs/surfaces/checkout/reference/apis/discounts.doc.ts

@@ -2,6 +2,7 @@ import type {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
 
 import {
   CHECKOUT_API_PROPERTIES_DESCRIPTION,
+  getExample,
   getLinksByTag,
   STANDARD_API_PROPERTIES_DESCRIPTION,
 } from '../helper.docs';
@@ -41,6 +42,11 @@ const data: ReferenceEntityTemplateSchema = {
       type: 'UseDiscountCodesGeneratedType',
     },
   ],
+  defaultExample: getExample('discounts/discount-codes', ['jsx']),
+  examples: {
+    description: '',
+    examples: [getExample('discounts/apply-discount', ['jsx'])],
+  },
   related: getLinksByTag('apis'),
 };
 

packages/ui-extensions/docs/surfaces/checkout/reference/apis/gift-cards.doc.ts

@@ -2,6 +2,7 @@ import type {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
 
 import {
   CHECKOUT_API_PROPERTIES_DESCRIPTION,
+  getExample,
   getLinksByTag,
   STANDARD_API_PROPERTIES_DESCRIPTION,
 } from '../helper.docs';
@@ -35,6 +36,11 @@ const data: ReferenceEntityTemplateSchema = {
       type: 'UseApplyGiftCardChangeGeneratedType',
     },
   ],
+  defaultExample: getExample('gift-cards/applied-gift-cards', ['jsx']),
+  examples: {
+    description: '',
+    examples: [getExample('gift-cards/apply-gift-card', ['jsx'])],
+  },
   related: getLinksByTag('apis'),
 };
 

packages/ui-extensions/docs/surfaces/checkout/reference/apis/note.doc.ts

@@ -2,6 +2,7 @@ import type {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
 
 import {
   CHECKOUT_API_PROPERTIES_DESCRIPTION,
+  getExample,
   getLinksByTag,
   STANDARD_API_PROPERTIES_DESCRIPTION,
 } from '../helper.docs';
@@ -36,6 +37,11 @@ const data: ReferenceEntityTemplateSchema = {
       type: 'UseApplyNoteChangeGeneratedType',
     },
   ],
+  defaultExample: getExample('note/display-note', ['jsx']),
+  examples: {
+    description: '',
+    examples: [getExample('note/update-note', ['jsx'])],
+  },
   related: getLinksByTag('apis'),
 };
 

packages/ui-extensions/docs/surfaces/checkout/reference/apis/order.doc.ts

@@ -24,6 +24,10 @@ const data: ReferenceEntityTemplateSchema = {
   subCategory: 'Checkout APIs',
   type: 'API',
   defaultExample: getExample('order-confirmation/default', ['jsx']),
+  examples: {
+    description: '',
+    examples: [getExample('order-confirmation/first-order', ['jsx'])],
+  },
   definitions: [
     {
       title: 'OrderConfirmationApi',

packages/ui-extensions/docs/surfaces/checkout/reference/examples/address/billing-address.example.tsx

@@ -0,0 +1,31 @@
+import '@shopify/ui-extensions/preact';
+import {render} from 'preact';
+
+import {useBillingAddress} from '@shopify/ui-extensions/checkout/preact';
+
+export default function extension() {
+  render(<Extension />, document.body);
+}
+
+function Extension() {
+  const billingAddress = useBillingAddress();
+
+  if (!billingAddress) {
+    return null;
+  }
+
+  const formattedAddress = [
+    billingAddress.address1,
+    billingAddress.city,
+    billingAddress.provinceCode,
+    billingAddress.countryCode,
+  ]
+    .filter(Boolean)
+    .join(', ');
+
+  return (
+    <s-banner heading="Billing address">
+      {formattedAddress}
+    </s-banner>
+  );
+}

packages/ui-extensions/docs/surfaces/checkout/reference/examples/address/shipping-address.example.tsx

@@ -0,0 +1,30 @@
+import '@shopify/ui-extensions/preact';
+import {render} from 'preact';
+
+import {useShippingAddress} from '@shopify/ui-extensions/checkout/preact';
+
+export default function extension() {
+  render(<Extension />, document.body);
+}
+
+function Extension() {
+  const shippingAddress = useShippingAddress();
+
+  if (!shippingAddress) {
+    return (
+      <s-banner>
+        No shipping address has been entered yet.
+      </s-banner>
+    );
+  }
+
+  return (
+    <s-stack>
+      <s-text>
+        Shipping to: {shippingAddress.city},{' '}
+        {shippingAddress.provinceCode},{' '}
+        {shippingAddress.countryCode}
+      </s-text>
+    </s-stack>
+  );
+}

packages/ui-extensions/docs/surfaces/checkout/reference/examples/buyer-identity/customer-info.example.tsx

@@ -0,0 +1,30 @@
+import '@shopify/ui-extensions/preact';
+import {render} from 'preact';
+
+import {useCustomer} from '@shopify/ui-extensions/checkout/preact';
+
+export default function extension() {
+  render(<Extension />, document.body);
+}
+
+function Extension() {
+  const customer = useCustomer();
+
+  if (!customer) {
+    return null;
+  }
+
+  const name =
+    customer.fullName ?? 'Customer';
+
+  return (
+    <s-banner heading="Welcome back">
+      {name}, you have {customer.ordersCount}{' '}
+      previous{' '}
+      {customer.ordersCount === 1
+        ? 'order'
+        : 'orders'}{' '}
+      with us.
+    </s-banner>
+  );
+}

packages/ui-extensions/docs/surfaces/checkout/reference/examples/buyer-identity/purchasing-company.example.tsx

@@ -0,0 +1,25 @@
+import '@shopify/ui-extensions/preact';
+import {render} from 'preact';
+
+import {usePurchasingCompany} from '@shopify/ui-extensions/checkout/preact';
+
+export default function extension() {
+  render(<Extension />, document.body);
+}
+
+function Extension() {
+  const purchasingCompany = usePurchasingCompany();
+
+  if (!purchasingCompany) {
+    return null;
+  }
+
+  return (
+    <s-banner heading="B2B order">
+      Purchasing on behalf of{' '}
+      {purchasingCompany.company.name},{' '}
+      location:{' '}
+      {purchasingCompany.location.name}
+    </s-banner>
+  );
+}

packages/ui-extensions/docs/surfaces/checkout/reference/examples/cart-lines/summary.example.tsx

@@ -0,0 +1,42 @@
+import '@shopify/ui-extensions/preact';
+import {render} from 'preact';
+
+import {useCartLines} from '@shopify/ui-extensions/checkout/preact';
+
+export default function extension() {
+  render(<Extension />, document.body);
+}
+
+function Extension() {
+  const cartLines = useCartLines();
+
+  const totalQuantity = cartLines.reduce(
+    (sum, line) => sum + line.quantity,
+    0,
+  );
+
+  return (
+    <s-stack>
+      <s-text type="strong">
+        {totalQuantity}{' '}
+        {totalQuantity === 1 ? 'item' : 'items'}{' '}
+        in your cart
+      </s-text>
+      {cartLines.map((line) => (
+        <s-stack
+          key={line.id}
+          direction="inline"
+          gap="small-200"
+        >
+          <s-text>
+            {line.merchandise.title} × {line.quantity}
+          </s-text>
+          <s-text>
+            {line.cost.totalAmount.amount}{' '}
+            {line.cost.totalAmount.currencyCode}
+          </s-text>
+        </s-stack>
+      ))}
+    </s-stack>
+  );
+}

packages/ui-extensions/docs/surfaces/checkout/reference/examples/checkout-token/default.example.tsx

@@ -0,0 +1,22 @@
+import '@shopify/ui-extensions/preact';
+import {render} from 'preact';
+
+import {useCheckoutToken} from '@shopify/ui-extensions/checkout/preact';
+
+export default function extension() {
+  render(<Extension />, document.body);
+}
+
+function Extension() {
+  const checkoutToken = useCheckoutToken();
+
+  if (!checkoutToken) {
+    return null;
+  }
+
+  return (
+    <s-text>
+      Checkout reference: {checkoutToken}
+    </s-text>
+  );
+}

packages/ui-extensions/docs/surfaces/checkout/reference/examples/checkout-token/support-message.example.tsx

@@ -0,0 +1,24 @@
+import '@shopify/ui-extensions/preact';
+import {render} from 'preact';
+
+import {useCheckoutToken} from '@shopify/ui-extensions/checkout/preact';
+
+export default function extension() {
+  render(<Extension />, document.body);
+}
+
+function Extension() {
+  const checkoutToken = useCheckoutToken();
+
+  if (!checkoutToken) {
+    return null;
+  }
+
+  return (
+    <s-banner heading="Need help?">
+      Please include reference ID{' '}
+      <s-text type="strong">{checkoutToken}</s-text>{' '}
+      when contacting support.
+    </s-banner>
+  );
+}