Improved descriptions for targets, APIs, and components

Author: mcvinci

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

@@ -7,28 +7,15 @@ const generateJsxCodeBlockForActionApi = (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.PosProductDetailsBlockRender}
-- ${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 `shopify.action` to launch full-screen modal experiences.',
       type: 'ActionApiContent',
     },
   ],

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

@@ -7,31 +7,15 @@ const generateJsxCodeBlockForCartApi = (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.PosProductDetailsBlockRender}
-- ${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. The API supports both individual and bulk operations for efficient cart manipulation, with [selling plan functionality](/docs/apps/build/purchase-options/subscriptions/selling-plans) and error handling.',
   isVisualComponent: false,
   type: 'APIs',
   definitions: [
     {
       title: 'CartApi',
-      description: '',
+      description:
+        'The `CartApi` object provides access to cart management functionality and real-time cart state monitoring. Access these properties through `shopify.cart` to interact with the current POS cart.',
       type: 'CartApiContent',
     },
   ],

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

@@ -9,19 +9,15 @@ const generateJsxCodeBlockForCartLineItemApi = (
 
 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 the current line item. Access this property through `api.cartLineItem` to interact with the current line item context.',
       type: 'CartLineItemApi',
     },
   ],

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

@@ -9,13 +9,14 @@ const generateJsxCodeBlockForConnectivityApi = (
 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 access to current connectivity information and change notifications. Access these properties through `shopify.connectivity` to monitor network status.',
       type: 'ConnectivityApiContent',
     },
   ],

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

@@ -7,20 +7,15 @@ const generateJsxCodeBlockForCustomerApi = (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 `shopify.customer` to interact with the current customer context.',
       type: 'CustomerApiContent',
     },
   ],

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

@@ -7,13 +7,14 @@ const generateJsxCodeBlockForDeviceApi = (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 `shopify.device` to retrieve device details and check device characteristics.',
       type: 'DeviceApiContent',
     },
   ],

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

@@ -9,21 +9,15 @@ const generateJsxCodeBlockForDraftOrderApi = (
 
 const data: ReferenceEntityTemplateSchema = {
   name: 'Draft Order API',
-  description: `
-The Draft Order API provides an extension with data about the current draft order.
-
-
-#### Supporting targets
-- ${TargetLink.PosDraftOrderDetailsActionMenuItemRender}
-- ${TargetLink.PosDraftOrderDetailsActionRender}
-- ${TargetLink.PosDraftOrderDetailsBlockRender}
-`,
+  description:
+    'The Draft Order API provides read-only access to draft order data. Use this API to get draft order information and build contextual experiences based on the selected draft order context. The API offers draft order details for implementing order-specific functionality and workflows.',
   isVisualComponent: false,
   type: 'APIs',
   definitions: [
     {
       title: 'DraftOrderApi',
-      description: '',
+      description:
+        'The `DraftOrderApi` object provides access to draft order data. Access this property through `api.draftOrder` to interact with the current draft order context.',
       type: 'DraftOrderApiContent',
     },
   ],

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

@@ -7,13 +7,14 @@ const generateJsxCodeBlockForLocaleApi = (title: string, fileName: string) =>
 const data: ReferenceEntityTemplateSchema = {
   name: 'Locale API',
   description:
-    "The Locale API allows the extension to retrieve the merchant's locale.",
+    "The Locale API provides access to the merchant's current locale information in [IETF format](https://en.wikipedia.org/wiki/IETF_language_tag), allowing you to internationalize your extension content and respond to locale changes in real time. The API enables both immediate locale access and dynamic updates when merchants change their language settings.",
   isVisualComponent: false,
   type: 'APIs',
   definitions: [
     {
       title: 'LocaleApi',
-      description: '',
+      description:
+        'The `LocaleApi` object provides access to current locale information and change notifications. Access these properties through `shopify.locale` to retrieve and monitor locale data.',
       type: 'LocaleApiContent',
     },
   ],

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

@@ -9,28 +9,21 @@ const generateJsxCodeBlockForNavigationApi = (
 
 const data: ReferenceEntityTemplateSchema = {
   name: 'Navigation API',
-  description: `
-The Navigation API enables POS UI extension to navigate between screens.
-
-#### Supporting targets
-- ${TargetLink.PosHomeModalRender}
-- ${TargetLink.PosPurchasePostActionRender}
-- ${TargetLink.PosProductDetailsActionRender}
-- ${TargetLink.PosOrderDetailsActionRender}
-- ${TargetLink.PosDraftOrderDetailsActionRender}
-- ${TargetLink.PosCustomerDetailsActionRender}
-`,
+  description:
+    'The Navigation API provides web-standard navigation functionality for POS UI extensions, allowing you to navigate between URLs, manage navigation history, and handle navigation events within modal interfaces. The API is available globally as the `navigation` object and follows web platform standards.',
   isVisualComponent: false,
   type: 'APIs',
   definitions: [
     {
       title: 'NavigationApi',
-      description: '',
+      description:
+        'The global `navigation` object provides web-standard navigation functionality. Access these properties and methods directly through the global `navigation` object to manage navigation within modal interfaces.',
       type: 'Navigation',
     },
     {
       title: 'Window',
-      description: '',
+      description:
+        'The global `window` object provides control over the extension screen lifecycle. Access these properties and methods directly through the global `window` object to manage the modal interface.',
       type: 'Window',
     },
   ],

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

@@ -7,23 +7,15 @@ const generateJsxCodeBlockForOrderApi = (title: string, fileName: string) =>
 
 const data: ReferenceEntityTemplateSchema = {
   name: 'Order API',
-  description: `
-The Order API provides an extension with data about the current order.
-
-#### Supporting targets
-- ${TargetLink.PosPurchasePostActionMenuItemRender}
-- ${TargetLink.PosPurchasePostActionRender}
-- ${TargetLink.PosPurchasePostBlockRender}
-- ${TargetLink.PosOrderDetailsActionMenuItemRender}
-- ${TargetLink.PosOrderDetailsActionRender}
-- ${TargetLink.PosOrderDetailsBlockRender}
-`,
+  description:
+    'The Order API provides read-only access to order data. Use this API to get order information and build contextual experiences based on the selected order context. The API offers order details for implementing order-specific functionality and workflows.',
   isVisualComponent: false,
   type: 'APIs',
   definitions: [
     {
       title: 'OrderApi',
-      description: '',
+      description:
+        'The `OrderApi` object provides access to order data. Access this property through `shopify.order` to interact with the current order context.',
       type: 'OrderApiContent',
     },
   ],