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

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

@@ -7,46 +7,39 @@ 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.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',
   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.",
       },
     ],
   },

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

@@ -7,175 +7,207 @@ const generateCodeBlockForCartApi = (title: string, fileName: string) =>
 
 const data: ReferenceEntityTemplateSchema = {
   name: 'Cart API',
-  description: `
-The Cart API enables UI Extensions to manage and interact with POS cart contents, such as discounts, line items, and customer details. It provides a comprehensive set of functions for adding and removing items, alongside a subscribable object that keeps the UI Extension updated with real-time changes to the cart.
-
-#### Supporting targets
-- ${TargetLink.PosHomeTileRender}
-- ${TargetLink.PosHomeModalRender}
-- ${TargetLink.PosProductDetailsActionMenuItemRender}
-- ${TargetLink.PosProductDetailsActionRender}
-- ${TargetLink.PosCustomerDetailsActionMenuItemRender}
-- ${TargetLink.PosCustomerDetailsActionRender}
-- ${TargetLink.PosCustomerDetailsBlockRender}
-- ${TargetLink.PosOrderDetailsActionMenuItemRender}
-- ${TargetLink.PosOrderDetailsActionRender}
-- ${TargetLink.PosOrderDetailsBlockRender}
-- ${TargetLink.PosDraftOrderDetailsActionMenuItemRender}
-- ${TargetLink.PosDraftOrderDetailsActionRender}
-- ${TargetLink.PosDraftOrderDetailsBlockRender}
-`,
+  description:
+    'The Cart API provides comprehensive access to POS cart management functionality, enabling extensions to read cart state, modify line items, apply discounts, manage customer information, and handle cart properties through a subscribable interface that delivers real-time updates. The API supports both individual and bulk operations for efficient cart manipulation.',
   isVisualComponent: false,
   type: 'APIs',
   definitions: [
     {
       title: 'CartApi',
-      description: '',
+      description:
+        'The `CartApi` object provides access to cart management methods and subscribable cart state. Access these methods through `api.cart` to build cart-aware extensions that respond to real-time cart updates.',
       type: 'CartApiContent',
     },
   ],
   category: 'APIs',
   related: [],
   examples: {
-    description: 'Examples of using the Cart API',
+    description:
+      'Learn how to manage cart contents, apply discounts, handle customer information, and track cart changes in real time.',
     examples: [
       {
         codeblock: generateCodeBlockForCartApi(
-          'Subscribe to cart changes.',
-          'subscribable',
+          'Add a custom sale item to the cart',
+          'add-custom-sale',
         ),
+        description:
+          "Create and add a custom sale item that isn't tied to an existing product in your catalog. This example demonstrates using `addCustomSale()` to add a line item with a custom title, quantity, price, and tax settings—useful for services, custom orders, or special charges.",
       },
       {
         codeblock: generateCodeBlockForCartApi(
-          'Apply a cart level discount',
-          'apply-cart-discount',
+          'Add a new address to the customer',
+          'add-address',
         ),
+        description:
+          "Create and add a new address to the customer associated with the cart. This example shows how to use `addAddress()` to add a complete address with street, city, province, name, and country information to the customer's profile for shipping or billing purposes.",
       },
       {
         codeblock: generateCodeBlockForCartApi(
-          'Apply a cart level discount code',
-          'apply-cart-code-discount',
+          'Add a product to the cart',
+          'add-line-item',
         ),
+        description:
+          "Add a product to the cart by specifying its variant ID and quantity. This example uses `addLineItem()` to add a product variant with the specified quantity, returning the new line item's UUID for future reference or manipulation.",
       },
       {
         codeblock: generateCodeBlockForCartApi(
-          'Remove all the discounts on the cart and line items',
-          'remove-all-discounts',
+          'Add custom properties to a line item',
+          'add-line-item-properties',
         ),
+        description:
+          "Attach custom key-value metadata to a specific line item using its UUID. This example uses `addLineItemProperties()` to add an `'Engraving'` property to a particular line item, useful for storing item-specific customizations, notes, or tracking data.",
       },
       {
         codeblock: generateCodeBlockForCartApi(
-          'Set a custom discount on a line item',
-          'set-line-item-discount',
+          'Add custom properties to multiple line items',
+          'bulk-add-line-item-properties',
         ),
+        description:
+          'Attach different custom properties to multiple line items simultaneously in a single operation. This example shows how to use `bulkAddLineItemProperties()` to efficiently add unique engraving text to multiple items at once, reducing API calls and improving performance.',
       },
       {
         codeblock: generateCodeBlockForCartApi(
-          'Set a custom discount on multiple line items',
-          'bulk-set-line-item-discounts',
+          'Add custom properties to the cart',
+          'add-cart-properties',
         ),
+        description:
+          "Attach custom key-value metadata to the cart for tracking, integrations, or additional context. This example uses `addCartProperties()` to add an `'Engraving'` property to the cart, which merges with existing properties and overwrites duplicate keys.",
       },
       {
         codeblock: generateCodeBlockForCartApi(
-          'Remove a discount on a line item',
-          'remove-line-item-discount',
+          'Apply a discount code to the cart',
+          'apply-cart-code-discount',
         ),
+        description:
+          "Add a discount to the cart using a discount code. This example shows how to apply the discount code `'SUMMER_2024'` using the `addCartCodeDiscount()` method, which validates and applies the code server-side if it's valid and applicable to the current cart.",
       },
       {
         codeblock: generateCodeBlockForCartApi(
-          'Clear the entire cart',
-          'clear-cart',
+          'Apply a discount to a line item',
+          'set-line-item-discount',
         ),
+        description:
+          "Add a discount to an individual line item in the cart using its UUID. This example applies a 10% discount titled `'Summer discount'` to a specific line item using the `setLineItemDiscount()` method, allowing you to target discounts at particular products.",
       },
       {
         codeblock: generateCodeBlockForCartApi(
-          'Set the customer in the cart',
-          'set-customer',
+          'Apply a percentage discount to the cart',
+          'apply-cart-discount',
         ),
+        description:
+          "Add a cart-level discount that applies to the total cart value. This example demonstrates applying a 10% discount titled `'Summer discount'` to the cart using the `applyCartDiscount()` method with the `Percentage` discount type.",
       },
       {
         codeblock: generateCodeBlockForCartApi(
-          'Remove the customer in the cart',
-          'remove-customer',
+          'Apply different discounts to multiple line items',
+          'bulk-set-line-item-discounts',
         ),
+        description:
+          'Add discounts to multiple line items simultaneously using a single operation. This example shows how to use `bulkSetLineItemDiscounts()` to apply different discount types and amounts to multiple items efficiently—one gets a 10% percentage discount while another receives a $15 fixed amount discount.',
       },
       {
         codeblock: generateCodeBlockForCartApi(
-          'Add a custom sale to the cart',
-          'add-custom-sale',
+          'Associate a customer with the cart',
+          'set-customer',
         ),
+        description:
+          'Associate a customer with the cart using their ID to enable customer-specific features. This example shows how to use `setCustomer()` to associate a customer, which enables personalized pricing, applicable discounts, loyalty benefits, and streamlines the checkout process.',
       },
       {
         codeblock: generateCodeBlockForCartApi(
-          'Add a line item to the cart',
-          'add-line-item',
+          'Attribute a staff member to a line item',
+          'set-attributed-staff-to-line-item',
         ),
+        description:
+          'Assign a staff member to an individual line item for detailed sales tracking. This example demonstrates using `setAttributedStaffToLineItem()` to track which staff member was responsible for selling a specific item, enabling item-level commission tracking and performance analysis.',
       },
       {
         codeblock: generateCodeBlockForCartApi(
-          'Remove a line item from the cart',
-          'remove-line-item',
+          'Attribute a staff member to the cart',
+          'set-attributed-staff',
         ),
+        description:
+          'Assign a staff member to the cart for sales tracking and commission purposes. This example uses `setAttributedStaff()` with a staff member ID to track who facilitated or managed the sale, useful for performance metrics and incentive calculations.',
       },
       {
         codeblock: generateCodeBlockForCartApi(
-          'Add custom properties to the cart',
-          'add-cart-properties',
+          'Clear all items from the cart',
+          'clear-cart',
         ),
+        description:
+          'Empty the cart completely, removing all line items, discounts, and properties. This example uses `clearCart()` to reset the cart to its initial empty state while preserving the customer association if present, useful for starting a new transaction or canceling a sale.',
       },
       {
         codeblock: generateCodeBlockForCartApi(
-          'Remove custom properties from the cart',
-          'remove-cart-properties',
+          'Delete a customer address',
+          'delete-address',
         ),
+        description:
+          "Remove a specific address from the customer's profile using its ID. This example demonstrates using `deleteAddress()` to permanently delete an address from the customer associated with the cart, useful for cleaning up outdated or incorrect addresses.",
       },
       {
         codeblock: generateCodeBlockForCartApi(
-          'Add custom properties to a line item',
-          'add-line-item-properties',
+          'Monitor cart updates in real time',
+          'subscribable',
         ),
+        description:
+          'Subscribe to cart state changes to display dynamic information based on cart contents. This example shows how to react to cart updates and display the current number of line items in the cart, automatically updating the tile subtitle whenever the cart changes.',
       },
       {
         codeblock: generateCodeBlockForCartApi(
-          'Add custom properties to multiple line items',
-          'bulk-add-line-item-properties',
+          'Remove a discount from a line item',
+          'remove-line-item-discount',
         ),
+        description:
+          "Clear the discount from an individual line item while leaving other cart discounts intact. This example uses `removeLineItemDiscount()` with the line item's UUID to remove only that item's discount without affecting cart-level or other line item discounts.",
       },
       {
         codeblock: generateCodeBlockForCartApi(
-          'Remove custom properties from a line item',
-          'remove-line-item-properties',
+          'Remove a line item from the cart',
+          'remove-line-item',
         ),
+        description:
+          'Delete a line item from the cart using its UUID. This example demonstrates using `removeLineItem()` to completely remove a specific item along with any associated discounts or properties, without affecting other cart contents.',
       },
       {
         codeblock: generateCodeBlockForCartApi(
-          'Set an attributed staff member on the cart',
-          'set-attributed-staff',
+          'Remove all discounts from cart and line items',
+          'remove-all-discounts',
         ),
+        description:
+          "Clear all discounts applied to both the cart and individual line items in a single operation. This example uses `removeAllDiscounts(true)` to remove all discounts and disable automatic discounts from being reapplied, giving you full control over the cart's discount state.",
       },
       {
         codeblock: generateCodeBlockForCartApi(
-          'Set an attributed staff member on a line item',
-          'set-attributed-staff-to-line-item',
+          'Remove custom properties from a line item',
+          'remove-line-item-properties',
         ),
+        description:
+          "Delete specific properties from a line item by its UUID and property keys. This example demonstrates using `removeLineItemProperties()` to remove the `'Engraving'` property from a specific line item while preserving other line item properties and data.",
       },
       {
         codeblock: generateCodeBlockForCartApi(
-          'Add an address to the customer in the cart',
-          'add-address',
+          'Remove custom properties from the cart',
+          'remove-cart-properties',
         ),
+        description:
+          "Delete specific cart properties by their keys while leaving other properties intact. This example demonstrates using `removeCartProperties()` to remove the `'Engraving'` property from the cart without affecting other custom properties or cart data.",
       },
       {
         codeblock: generateCodeBlockForCartApi(
-          'Delete an address corresponding to an ID',
-          'delete-address',
+          'Remove the customer from the cart',
+          'remove-customer',
         ),
+        description:
+          'Disassociate the customer from the cart and convert it to a guest cart. This example uses `removeCustomer()` to remove customer-specific pricing, discounts, and personalization while preserving all cart contents and line items.',
       },
       {
         codeblock: generateCodeBlockForCartApi(
-          'Set the default address of the customer in the cart',
+          "Set a customer's default address",
           'update-default-address',
         ),
+        description:
+          "Update which address is marked as the default for the customer in the cart. This example uses `updateDefaultAddress()` with an address ID to set the customer's primary address, which will be automatically selected for future transactions.",
       },
     ],
   },

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

@@ -7,26 +7,30 @@ 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',
   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.',
       },
     ],
   },