Merge pull request #3563 from Shopify/pos-ui-extensions-2025-07-api-prop-descriptions

[POS UI extensions]: Improved target, API, component descriptions for 2025-07

Author: mcvinci

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

@@ -7,53 +7,58 @@ const generateCodeBlockForActionApi = (title: string, fileName: string) =>
 
 const data: ReferenceEntityTemplateSchema = {
   name: 'Action API',
-  description: `
-The Action API allows an action extension to modally present its corresponding modal target.
-
-#### Supporting targets
-- ${TargetLink.PosHomeTileRender}
-- ${TargetLink.PosPurchasePostActionMenuItemRender}
-- ${TargetLink.PosPurchasePostBlockRender}
-- ${TargetLink.PosReturnPostActionMenuItemRender}
-- ${TargetLink.PosReturnPostBlockRender}
-- ${TargetLink.PosExchangePostActionMenuItemRender}
-- ${TargetLink.PosExchangePostBlockRender}
-- ${TargetLink.PosOrderDetailsActionMenuItemRender}
-- ${TargetLink.PosOrderDetailsBlockRender}
-- ${TargetLink.PosProductDetailsActionMenuItemRender}
-- ${TargetLink.PosCustomerDetailsActionMenuItemRender}
-- ${TargetLink.PosCustomerDetailsBlockRender}
-- ${TargetLink.PosDraftOrderDetailsActionMenuItemRender}
-- ${TargetLink.PosDraftOrderDetailsBlockRender}
-`,
+  description:
+    'The Action API provides modal presentation functionality for POS UI extensions, allowing you to launch full-screen modal interfaces from menu items, tiles, and block targets. The API enables navigation between different targets within your extension.',
   isVisualComponent: false,
   type: 'APIs',
   definitions: [
     {
       title: 'ActionApi',
-      description: '',
+      description:
+        'The `ActionApi` object provides methods for presenting modal interfaces. Access these methods through `api.action` to launch full-screen modal experiences.',
       type: 'ActionApiContent',
     },
   ],
-  category: 'APIs',
+  category: 'Target APIs',
+  subCategory: 'Standard APIs',
   related: [],
   examples: {
-    description: 'Examples of using the Action API.',
+    description:
+      'Learn how to present full-screen modals from tiles and menu items using the Action API.',
     examples: [
       {
         codeblock: generateCodeBlockForActionApi(
-          'Present a modal from post purchase.',
+          'Open a modal from a post-purchase action',
           'present-modal',
         ),
+        description:
+          "Create an action menu item that appears after a purchase is completed. When pressed, it launches a full-screen modal view using the Action API's `presentModal()` method, allowing you to display custom workflows or additional functionality in the post-purchase flow.",
       },
       {
         codeblock: generateCodeBlockForActionApi(
-          'Present a modal from smart grid.',
+          'Open a modal from a smart grid tile',
           'present-modal-tile',
         ),
+        description:
+          "Create a smart grid tile on the POS home screen that launches a full-screen modal when tapped. This example shows how to use the Action API to present detailed views or workflows from your app's home tile, providing quick access to extended functionality.",
       },
     ],
   },
+
+  subSections: [
+    {
+      type: 'Generic',
+      anchorLink: 'best-practices',
+      title: 'Best practices',
+      sectionContent: `\n- **Provide clear entry points:** Use descriptive button labels and titles that clearly indicate what the modal will contain or what action it will perform, helping users understand what to expect.\n- **Handle modal dismissal gracefully:** Ensure your modal-based workflows handle user dismissal, saving progress when possible and providing clear feedback about incomplete operations.\n`,
+    },
+    {
+      type: 'Generic',
+      anchorLink: 'limitations',
+      title: 'Limitations',
+      sectionContent: `\nEach extension can only present one modal at a time. Subsequent calls to \`presentModal()\` while a modal is already open may be ignored or replace the current modal.\n`,
+    },
+  ],
 };
 
 export default data;

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

@@ -7,42 +7,48 @@ const generateCodeBlockForCartLineItemApi = (title: string, fileName: string) =>
 
 const data: ReferenceEntityTemplateSchema = {
   name: 'Cart Line Item API',
-  description: `
-The Cart Line Item API provides an extension with data about the current Cart Line Item.
-
-#### Supporting targets
-- ${TargetLink.PosCartLineItemDetailsActionMenuItemRender}
-- ${TargetLink.PosCartLineItemDetailsActionRender}
-`,
+  description:
+    'The Cart Line Item API provides read-only access to a specific line item in the cart. Use this API to get line item details like product information, pricing, discounts, and custom properties. This allows you to build features that respond to the specific item a customer is viewing or interacting with.',
   isVisualComponent: false,
   type: 'APIs',
   definitions: [
     {
       title: 'CartLineItemApi',
-      description: '',
+      description:
+        'The `CartLineItemApi` object provides access to line item data. Access this through `api.lineItem` to retrieve information about the specific cart line item in context.',
       type: 'CartLineItemApi',
     },
   ],
   examples: {
-    description: 'Examples of using the Cart Line Item API.',
+    description:
+      'Learn how to access line item information and build contextual experiences based on specific cart items.',
     examples: [
       {
         codeblock: generateCodeBlockForCartLineItemApi(
-          'Retrieve the ID of the cart line item.',
+          'Get the current line item ID',
           'id',
         ),
+        description:
+          "Retrieve the unique identifier of the cart line item currently associated with the extension's context. This example shows how to access the line item ID from line item detail screens, enabling you to fetch additional item data, implement custom actions, or track item-specific operations.",
       },
     ],
   },
-  category: 'APIs',
-  related: [
+  category: 'Target APIs',
+  subCategory: 'Contextual APIs',
+  related: [],
+
+  subSections: [
     {
-      name: ExtensionTargetType.PosCartLineItemDetailsActionMenuItemRender,
-      url: '/docs/api/pos-ui-extensions/targets/pos-cart-line-item-details-action-menu-item-render',
+      type: 'Generic',
+      anchorLink: 'best-practices',
+      title: 'Best practices',
+      sectionContent: `\n- **Use line item context effectively:** Use the line item data to create contextual experiences—for example, showing different interfaces for gift cards versus regular products, or displaying vendor-specific information.\n- **Implement item-specific validation:** Use line item properties like \`taxable\` and \`isGiftCard\` to implement appropriate validation and business logic for different item types.\n- **Access related data efficiently:** Use \`productId\` and \`variantId\` to fetch additional product information when needed, but avoid unnecessary API calls by using the data already available in the line item.\n`,
     },
     {
-      name: ExtensionTargetType.PosCartLineItemDetailsActionRender,
-      url: '/docs/api/pos-ui-extensions/targets/pos-cart-line-item-details-action-render',
+      type: 'Generic',
+      anchorLink: 'limitations',
+      title: 'Limitations',
+      sectionContent: `\n- The API provides read-only access to line item data—use the Cart API for modifying line item properties, discounts, or other attributes.\n- Line item data reflects the current state and may not include real-time inventory or pricing updates until the cart is refreshed.\n`,
     },
   ],
 };

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

@@ -7,29 +7,49 @@ const generateCodeBlockForConnectivityApi = (title: string, fileName: string) =>
 const data: ReferenceEntityTemplateSchema = {
   name: 'Connectivity API',
   description:
-    'The Connectivity API enables POS UI extensions to retrieve device connectivity information, such as whether the device has an internet connection.',
+    'The Connectivity API provides access to device connectivity information, allowing you to monitor Internet connection status and respond to connectivity changes in real-time. The API enables both immediate connectivity checks and dynamic updates when network conditions change.',
   isVisualComponent: false,
   type: 'APIs',
   definitions: [
     {
       title: 'ConnectivityApi',
-      description: '',
+      description:
+        'The `ConnectivityApi` object provides methods for monitoring network connectivity. Access these methods through `api.connectivity` to check connection status and subscribe to connectivity changes.',
       type: 'ConnectivityApiContent',
     },
   ],
-  category: 'APIs',
+  category: 'Target APIs',
+  subCategory: 'Platform APIs',
   related: [],
   examples: {
-    description: 'Examples of using the Connectivity API',
+    description:
+      'Learn how to monitor internet connectivity status and respond to network changes in your extension.',
     examples: [
       {
         codeblock: generateCodeBlockForConnectivityApi(
-          'Subscribe to connectivity changes.',
+          'Monitor network connectivity changes',
           'subscribable',
         ),
+        description:
+          'Subscribe to connectivity state changes to respond when the device goes online or offline. This example demonstrates using the connectivity subscription to track network status and display the current connection state, allowing your extension to adapt behavior based on network availability.',
       },
     ],
   },
+
+  subSections: [
+    {
+      type: 'Generic',
+      anchorLink: 'best-practices',
+      title: 'Best practices',
+      sectionContent: `\n- **Design for connectivity awareness:** Design your extension to handle network interruptions, informing users when network-dependent features are unavailable and providing clear guidance on next steps.\n- **Provide clear connectivity feedback:** Display connectivity status to users when it affects functionality, helping them understand why certain features may be limited or unavailable.\n- **Queue operations during outages:** Implement queuing mechanisms for non-critical operations that can be deferred until connectivity is restored.\n`,
+    },
+    {
+      type: 'Generic',
+      anchorLink: 'limitations',
+      title: 'Limitations',
+      sectionContent: `\n- The Connectivity API provides read-only access to connectivity information and can't be used to control or modify network settings on the device.\n- \`RemoteSubscribable\` supports only one subscription at a time. Use \`makeStatefulSubscribable\` if you need multiple components to subscribe to connectivity changes simultaneously.\n- Connectivity status reflects Internet connectivity only and may not indicate the quality or speed of the connection, which could affect API performance.\n- The API monitors general Internet connectivity but doesn't provide specific information about Shopify service availability or API endpoint availability.\n`,
+    },
+  ],
 };
 
 export default data;

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

@@ -7,43 +7,48 @@ const generateCodeBlockForCustomerApi = (title: string, fileName: string) =>
 
 const data: ReferenceEntityTemplateSchema = {
   name: 'Customer API',
-  description: `
-The customer API provides an extension with data about the current customer.
-
-#### Supporting targets
-- ${TargetLink.PosCustomerDetailsActionMenuItemRender}
-- ${TargetLink.PosCustomerDetailsActionRender}
-- ${TargetLink.PosCustomerDetailsBlockRender}
-`,
+  description:
+    'The Customer API provides read-only access to customer data. Use this API to get customer information and build personalized experiences based on the selected customer context. The API offers the customer identifier for linking to customer data and enabling customer-specific features.',
   isVisualComponent: false,
   type: 'APIs',
   definitions: [
     {
       title: 'CustomerApi',
-      description: '',
+      description:
+        'The `CustomerApi` object provides access to customer data. Access this property through `api.customer` to interact with the current customer context.',
       type: 'CustomerApiContent',
     },
   ],
   examples: {
-    description: 'Examples of using the Customer API.',
+    description:
+      'Learn how to access customer information and build personalized experiences based on customer context.',
     examples: [
       {
         codeblock: generateCodeBlockForCustomerApi(
-          'Retrieve the ID of the customer.',
+          'Get the current customer ID',
           'id',
         ),
+        description:
+          "Retrieve the unique identifier of the customer currently associated with the extension's context. This example shows how to access the customer ID from customer details screens, enabling you to fetch additional customer data, track customer-specific actions, or link to external systems.",
       },
     ],
   },
-  category: 'APIs',
-  related: [
+  category: 'Target APIs',
+  subCategory: 'Contextual APIs',
+  related: [],
+
+  subSections: [
     {
-      name: ExtensionTargetType.PosCustomerDetailsActionMenuItemRender,
-      url: '/docs/api/pos-ui-extensions/targets/pos-customer-details-action-menu-item-render',
+      type: 'Generic',
+      anchorLink: 'best-practices',
+      title: 'Best practices',
+      sectionContent: `\n- **Implement customer-specific features:** Use the customer context to enable personalized functionality like customer-specific pricing, loyalty program integration, or customized product recommendations.\n- **Validate customer access:** Verify that the customer ID is valid before performing customer-specific operations or external API calls.\n`,
     },
     {
-      name: ExtensionTargetType.PosCustomerDetailsActionRender,
-      url: '/docs/api/pos-ui-extensions/targets/pos-customer-details-action-render',
+      type: 'Generic',
+      anchorLink: 'limitations',
+      title: 'Limitations',
+      sectionContent: `\n- The API provides only the customer identifier—use Shopify APIs or external systems to fetch additional customer details like name, email, or purchase history.\n- Customer data reflects the current POS session and may not include real-time updates from other channels until the session is refreshed.\n`,
     },
   ],
 };

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

@@ -7,41 +7,62 @@ const generateCodeBlockForDeviceApi = (title: string, fileName: string) =>
 const data: ReferenceEntityTemplateSchema = {
   name: 'Device API',
   description:
-    'The Device API allows the UI Extension to retrieve device information including the device name and ID.',
+    'The Device API provides access to device information and capabilities, allowing you to retrieve device details, check device types, and adapt your extension behavior based on the POS hardware characteristics. The API enables device-aware functionality and responsive design based on device form factors.',
   isVisualComponent: false,
   type: 'APIs',
   definitions: [
     {
       title: 'DeviceApi',
-      description: '',
+      description:
+        'The `DeviceApi` object provides access to device information and capabilities. Access these properties and methods through `api.device` to retrieve device details and check device characteristics.',
       type: 'DeviceApiContent',
     },
   ],
-  category: 'APIs',
+  category: 'Target APIs',
+  subCategory: 'Platform APIs',
   related: [],
   examples: {
-    description: 'Examples of using the Device API.',
+    description:
+      'Learn how to access device information and adapt your extension based on hardware characteristics.',
     examples: [
       {
         codeblock: generateCodeBlockForDeviceApi(
-          'Retrieve name of the device.',
-          'name',
+          'Check if the device is a tablet',
+          'tablet',
         ),
+        description:
+          'Check whether the extension is running on a tablet form factor. This example uses the `isTablet` property to determine the device type, allowing you to adapt layouts, adjust component sizing, or enable tablet-specific features for larger screen experiences.',
       },
       {
         codeblock: generateCodeBlockForDeviceApi(
-          'Retrieve the ID of the device.',
+          'Get the device ID',
           'device-id',
         ),
+        description:
+          'Retrieve the unique identifier for the device running your extension. This example accesses the device ID, enabling device-specific tracking, settings synchronization, or associating actions with specific POS terminals for audit trails and analytics.',
       },
       {
-        codeblock: generateCodeBlockForDeviceApi(
-          'Check if device is a tablet.',
-          'tablet',
-        ),
+        codeblock: generateCodeBlockForDeviceApi('Get the device name', 'name'),
+        description:
+          "Retrieve the human-readable name of the device running your extension. This example accesses the device's name, which can be useful for debugging, analytics, device-specific customization, or displaying device information to staff members.",
       },
     ],
   },
+
+  subSections: [
+    {
+      type: 'Generic',
+      anchorLink: 'best-practices',
+      title: 'Best practices',
+      sectionContent: `\n- **Handle async device queries:** Handle the Promise-based device methods with async/await or \`.then()\` patterns, and implement appropriate error handling for device query failures.\n- **Cache device information appropriately:** Consider caching device information after the initial query to avoid repeated async calls, but ensure you handle cases where device characteristics might change during the session.\n- **Provide device-appropriate experiences:** Design different user experiences for tablets versus other devices, taking advantage of larger screens while ensuring functionality works across all supported device types.\n`,
+    },
+    {
+      type: 'Generic',
+      anchorLink: 'limitations',
+      title: 'Limitations',
+      sectionContent: `\n- Device information queries are asynchronous and may take time to resolve, so always handle the Promise-based responses appropriately in your extension logic.\n- The Device API provides read-only access to device information and can't be used to modify device settings or capabilities.\n- Device type detection is limited to basic form factor identification (tablet vs. non-tablet) and doesn't provide detailed hardware specifications or capabilities.\n`,
+    },
+  ],
 };
 
 export default data;