diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/action-api.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/action-api.doc.ts index 24919209ba..bd5f75c71a 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/action-api.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/action-api.doc.ts @@ -7,49 +7,62 @@ 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', + 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: ` +- **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. +- **Handle modal dismissal gracefully:** Ensure your modal-based workflows handle user dismissal, saving progress when possible and providing clear feedback about incomplete operations. + `, + }, + { + type: 'Generic', + anchorLink: 'limitations', + title: 'Limitations', + sectionContent: ` +Each 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. + `, + }, + ], }; export default data; diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/cart-api.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/cart-api.doc.ts index c5f5501ddb..3937d1884c 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/cart-api.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/cart-api.doc.ts @@ -7,178 +7,234 @@ 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', + category: 'Target APIs', + subCategory: 'Contextual 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.", }, ], }, + subSections: [ + { + type: 'Generic', + anchorLink: 'best-practices', + title: 'Best practices', + sectionContent: ` +- **Manage subscriptions properly:** Remember that \`RemoteSubscribable\` supports only one subscription at a time. Use \`makeStatefulSubscribable\` if you need multiple components to subscribe to cart changes simultaneously. +- **Validate operations before execution:** Check cart editability and validate input data before performing cart operations to prevent errors and provide appropriate user feedback. +- **Use bulk operations for efficiency:** When performing multiple related operations, use bulk methods like \`bulkSetLineItemDiscounts\` and \`bulkAddLineItemProperties\` for better performance. +- **Handle errors gracefully:** Implement proper error handling for all cart operations, as they may fail due to inventory constraints, validation errors, or business rule violations. + `, + }, + { + type: 'Generic', + anchorLink: 'limitations', + title: 'Limitations', + sectionContent: ` +- \`RemoteSubscribable\` supports only one subscription at a time. Use \`makeStatefulSubscribable\` if you need multiple components to subscribe to cart events simultaneously. +- Cart operations may fail due to business rules, inventory constraints, or validation errors—always implement appropriate error handling. +- Some operations require specific preconditions. For example, customer must be present for address operations. + `, + }, + ], }; export default data; diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/connectivity-api.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/connectivity-api.doc.ts index 7fac3f6ec6..d903ad2b24 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/connectivity-api.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/connectivity-api.doc.ts @@ -7,29 +7,57 @@ 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: ` +- **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. +- **Provide clear connectivity feedback:** Display connectivity status to users when it affects functionality, helping them understand why certain features may be limited or unavailable. +- **Queue operations during outages:** Implement queuing mechanisms for non-critical operations that can be deferred until connectivity is restored. + `, + }, + { + type: 'Generic', + anchorLink: 'limitations', + title: 'Limitations', + sectionContent: ` +- The Connectivity API provides read-only access to connectivity information and can't be used to control or modify network settings on the device. +- \`RemoteSubscribable\` supports only one subscription at a time. Use \`makeStatefulSubscribable\` if you need multiple components to subscribe to connectivity changes simultaneously. +- Connectivity status reflects Internet connectivity only and may not indicate the quality or speed of the connection, which could affect API performance. +- The API monitors general Internet connectivity but doesn't provide specific information about Shopify service availability or API endpoint availability. + `, + }, + ], }; export default data; diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/customer-api.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/customer-api.doc.ts index 0f87ccc621..f6babe12b8 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/customer-api.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/customer-api.doc.ts @@ -7,43 +7,53 @@ 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: ` +- **Implement customer-specific features:** Use the customer context to enable personalized functionality like customer-specific pricing, loyalty program integration, or customized product recommendations. +- **Validate customer access:** Verify that the customer ID is valid before performing customer-specific operations or external API calls. + `, }, { - name: ExtensionTargetType.PosCustomerDetailsActionRender, - url: '/docs/api/pos-ui-extensions/targets/pos-customer-details-action-render', + type: 'Generic', + anchorLink: 'limitations', + title: 'Limitations', + sectionContent: ` +- The API provides only the customer identifier—use Shopify APIs or external systems to fetch additional customer details like name, email, or purchase history. +- Customer data reflects the current POS session and may not include real-time updates from other channels until the session is refreshed. + `, }, ], }; diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/device-api.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/device-api.doc.ts index d7775af36b..3dd6ee5709 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/device-api.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/device-api.doc.ts @@ -7,41 +7,69 @@ 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: ` +- **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. +- **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. +- **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. + `, + }, + { + type: 'Generic', + anchorLink: 'limitations', + title: 'Limitations', + sectionContent: ` +- Device information queries are asynchronous and may take time to resolve, so always handle the Promise-based responses appropriately in your extension logic. +- The Device API provides read-only access to device information and can't be used to modify device settings or capabilities. +- Device type detection is limited to basic form factor identification (tablet vs. non-tablet) and doesn't provide detailed hardware specifications or capabilities. + `, + }, + ], }; export default data; diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/draft-order-api.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/draft-order-api.doc.ts index b297537101..67ca356933 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/draft-order-api.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/draft-order-api.doc.ts @@ -4,38 +4,56 @@ import {generateCodeBlock} from '../helpers/generateCodeBlock'; 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', }, ], examples: { - description: 'Examples of using the Draft Order API.', + description: + 'Learn how to access draft order information and build contextual experiences for draft order workflows.', examples: [ { codeblock: generateCodeBlock( - 'Retrieve the ID of the draft order.', + 'Get the current draft order ID', 'draft-order-api', 'id', ), + description: + "Retrieve the unique identifier of the draft order currently associated with the extension's context. This example shows how to access the draft order ID from draft order detail screens, enabling you to fetch additional order data, implement custom workflows, or integrate with external systems.", }, ], }, - category: 'APIs', + category: 'Target APIs', + subCategory: 'Contextual APIs', related: [], + subSections: [ + { + type: 'Generic', + anchorLink: 'best-practices', + title: 'Best practices', + sectionContent: ` +- **Implement draft order-specific features:** Use the draft order context to enable specialized functionality like draft order conversion, customer assignment, or order modification workflows. +- **Validate draft order access:** Verify that the draft order ID is valid before performing draft order-specific operations or external API calls. + `, + }, + { + type: 'Generic', + anchorLink: 'limitations', + title: 'Limitations', + sectionContent: ` +- The API provides only basic draft order information—use Shopify APIs or external systems to fetch additional draft order details like line items, totals, or timestamps. +- Draft order data reflects the current POS session and may not include real-time updates from other channels until the session is refreshed. + `, + }, + ], }; export default data; diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/locale-api.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/locale-api.doc.ts index 72939773bf..dc36143433 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/locale-api.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/locale-api.doc.ts @@ -7,29 +7,55 @@ const generateCodeBlockForLocaleApi = (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 through subscription callbacks. The API provides both immediate locale access and change notifications for dynamic internationalization.", 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 `api.locale` to retrieve and monitor locale data.', type: 'LocaleApiContent', }, ], - category: 'APIs', + category: 'Target APIs', + subCategory: 'Standard APIs', related: [], examples: { - description: 'Examples of using the Locale API', + description: + "Learn how to access locale information and internationalize your extension based on the merchant's language settings.", examples: [ { codeblock: generateCodeBlockForLocaleApi( - 'Subscribe to locale changes.', + 'Track locale changes in real time', 'subscribable', ), + description: + "Subscribe to locale changes to dynamically update your extension's content when the merchant switches languages. This example demonstrates monitoring locale updates and displaying the current locale in IETF format, allowing you to provide properly localized content and adapt to language preferences in real time.", }, ], }, + subSections: [ + { + type: 'Generic', + anchorLink: 'best-practices', + title: 'Best practices', + sectionContent: ` +- **Implement proper formatting:** Use the IETF locale format to implement proper date formatting, number formatting, currency display, and text direction based on the merchant's language and region preferences. +- **Provide fallback locale handling:** Implement fallback behavior for unsupported locales or when localization resources are unavailable, defaulting to a supported language like English. + `, + }, + { + type: 'Generic', + anchorLink: 'limitations', + title: 'Limitations', + sectionContent: ` +- The Locale API provides read-only access to locale information and can't be used to change the merchant's locale settings, which must be configured through POS system settings. +- \`RemoteSubscribable\` supports only one subscription at a time. Use \`makeStatefulSubscribable\` if you need multiple components to subscribe to locale changes simultaneously. +- The locale format follows IETF standards, but the specific locales available depend on POS system configuration and may vary between different Shopify POS installations. + `, + }, + ], }; export default data; diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/navigation-api.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/navigation-api.doc.ts index daf0901a4d..08b8096a08 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/navigation-api.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/navigation-api.doc.ts @@ -7,54 +7,65 @@ const generateCodeBlockForNavigationApi = (title: string, fileName: string) => 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 screen-based navigation functionality for POS UI extensions, allowing you to navigate between screens, manage navigation stacks, and dismiss modal interfaces within full-screen modal workflows. The API enables multi-screen experiences with parameter passing and navigation control.', 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: 'NavigationApiContent', }, ], - category: 'APIs', + category: 'Target APIs', + subCategory: 'Platform APIs', related: [], examples: { - description: 'Examples of using the Navigation API', + description: + 'Learn how to navigate between screens, manage navigation stacks, and control multi-screen modal experiences.', examples: [ { codeblock: generateCodeBlockForNavigationApi( - 'Navigate between two screens', + 'Create a multi-screen modal', 'two-screen', ), + description: + 'Create a navigation flow with multiple screens in a modal interface. This example shows how to set up a Navigator with two screens and navigate between them, enabling multi-step workflows, wizards, or detailed views within your extension.', }, - ], - exampleGroups: [ { - title: 'Navigation actions', - examples: [ - { - description: - 'Navigates to the specified screen. It is important to note that any screens you wish to navigate to must already exist in the Navigator.', - codeblock: generateCodeBlockForNavigationApi( - 'Navigate to a route in current navigation tree', - 'navigation-tree', - ), - }, - ], + codeblock: generateCodeBlockForNavigationApi( + 'Navigate to another screen', + 'navigation-tree', + ), + description: + 'Navigate programmatically to a specific screen in your navigation hierarchy. This example demonstrates using the global `navigation` object to push a new screen onto the navigation stack. Note that the target screen must already be defined in your Navigator component before you can navigate to it.', }, ], }, + subSections: [ + { + type: 'Generic', + anchorLink: 'best-practices', + title: 'Best practices', + sectionContent: ` +- **Handle navigation parameters effectively:** Use navigation parameters to pass data between screens, maintaining workflow context and user progress across screen transitions. +- **Implement proper screen management:** Design screens that can be pushed and popped. +- **Provide clear navigation controls:** Implement clear navigation controls and feedback so users understand their current location in the workflow and how to navigate between screens. + `, + }, + { + type: 'Generic', + anchorLink: 'limitations', + title: 'Limitations', + sectionContent: ` +- The Navigation API is only available in action (modal) targets and can't be used in action (menu item), block, or tile targets that don't support multi-screen navigation. +- Screen navigation is based on screen names and the navigation stack, which differs from URL-based navigation patterns found in web applications. +- Navigation parameters must be serializable and can't contain functions, complex objects, or circular references. + `, + }, + ], }; export default data; diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/order-api.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/order-api.doc.ts index 70cf293386..b05c62a0d5 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/order-api.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/order-api.doc.ts @@ -7,45 +7,63 @@ const generateCodeBlockForOrderApi = (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 `api.order` to interact with the current order context.', type: 'OrderApiContent', }, ], - category: 'APIs', + category: 'Target APIs', + subCategory: 'Contextual APIs', related: [], examples: { - description: 'Examples of using the Order API', + description: + 'Learn how to access order information and build contextual experiences based on completed orders.', examples: [ { codeblock: generateCodeBlockForOrderApi( - 'Basic usage of the Order API in an action', + 'Access order data in an action menu', 'basic-usage', ), + description: + 'Retrieve order information from action menu items on order detail screens. This example shows how to access the Order API to get the current order data, enabling you to build custom workflows, generate reports, or trigger integrations based on order details.', }, { codeblock: generateCodeBlockForOrderApi( - 'Display order details in a block', + 'Show order details in a block', 'display-in-block', ), + description: + 'Show order details within a custom block on order detail screens. This example demonstrates how to use the Order API to fetch and display order information in a persistent block, providing merchants with quick access to relevant order data or additional context.', }, ], }, + subSections: [ + { + type: 'Generic', + anchorLink: 'best-practices', + title: 'Best practices', + sectionContent: ` +- **Implement order-specific features:** Use the order context to enable specialized functionality like order fulfillment, customer communication, or order modification workflows. +- **Validate order access:** Verify that the order ID is valid before performing order-specific operations or external API calls. + `, + }, + { + type: 'Generic', + anchorLink: 'limitations', + title: 'Limitations', + sectionContent: ` +- The API provides only basic order information—use Shopify APIs or external systems to fetch additional order details like line items, totals, or fulfillment status. +- Order data reflects the current POS session and may not include real-time updates from other channels until the session is refreshed. + `, + }, + ], }; export default data; diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/product-api.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/product-api.doc.ts index 73c2c56be6..b1133f1f91 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/product-api.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/product-api.doc.ts @@ -7,42 +7,53 @@ const generateCodeBlockForProductApi = (title: string, fileName: string) => const data: ReferenceEntityTemplateSchema = { name: 'Product API', - description: ` -The Product API provides an extension with data about the current Product. - -#### Supporting targets -- ${TargetLink.PosProductDetailsActionMenuItemRender} -- ${TargetLink.PosProductDetailsActionRender} -`, + description: + 'The Product API provides read-only access to product data. Use this API to get product information and build contextual experiences based on the selected product context. The API offers product details for implementing product-specific functionality and workflows.', isVisualComponent: false, type: 'APIs', definitions: [ { title: 'ProductApi', - description: '', + description: + 'The `ProductApi` object provides access to product data. Access this property through `api.product` to interact with the current product context.', type: 'ProductApiContent', }, ], examples: { - description: 'Examples of using the Product API.', + description: + 'Learn how to access product information and build contextual experiences based on product context.', examples: [ { codeblock: generateCodeBlockForProductApi( - 'Retrieve the ID of the product.', + 'Get the current product ID', 'id', ), + description: + "Retrieve the unique identifier of the product currently associated with the extension's context. This example shows how to access the product ID from product detail screens, enabling you to fetch additional product data, implement custom actions, or integrate with inventory and pricing systems.", }, ], }, - category: 'APIs', - related: [ + category: 'Target APIs', + subCategory: 'Contextual APIs', + related: [], + subSections: [ { - name: ExtensionTargetType.PosProductDetailsActionMenuItemRender, - url: '/docs/api/pos-ui-extensions/targets/pos-product-details-action-menu-item-render', + type: 'Generic', + anchorLink: 'best-practices', + title: 'Best practices', + sectionContent: ` +- **Implement variant-specific features:** Use the variant ID to enable specialized functionality like variant-specific pricing, inventory checks, or cart operations. +- **Validate product access:** Verify that the product ID and variant ID are valid before performing product-specific operations or external API calls. + `, }, { - name: ExtensionTargetType.PosProductDetailsActionRender, - url: '/docs/api/pos-ui-extensions/targets/pos-product-details-action-render', + type: 'Generic', + anchorLink: 'limitations', + title: 'Limitations', + sectionContent: ` +- The API provides only basic product identifiers—use Shopify APIs or external systems to fetch additional product details like title, description, pricing, or inventory levels. +- Product data reflects the current POS session and may not include real-time updates from other channels until the session is refreshed. + `, }, ], }; diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/product-search-api.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/product-search-api.doc.ts index 8a3b2d2304..8643bcb7fe 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/product-search-api.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/product-search-api.doc.ts @@ -9,59 +9,96 @@ const generateCodeBlockForProductSearchApi = ( const data: ReferenceEntityTemplateSchema = { name: 'ProductSearch API', description: - 'The ProductSearch API gives extensions access to the native product search and fetching functionality of Shopify POS. The interface provides numerous functions to search for products by query, or to fetch the details of one or more products or product variants.', + 'The Product Search API provides access to POS native product search functionality, allowing you to search for products, fetch product details, and retrieve product variants with pagination support and flexible sorting options. The API enables both text-based search and direct product lookups by ID.', isVisualComponent: false, type: 'APIs', definitions: [ { title: 'ProductSearchApi', - description: '', + description: + 'The `ProductSearchApi` object provides methods for searching and fetching product data. Access these methods through `api.productSearch` to perform product searches and lookups.', type: 'ProductSearchApiContent', }, ], - category: 'APIs', + category: 'Target APIs', + subCategory: 'Standard APIs', related: [], examples: { - description: 'Examples of using the Cart API', + description: + 'Learn how to search for products, fetch product details, and retrieve variants using the native POS search functionality.', examples: [ { codeblock: generateCodeBlockForProductSearchApi( - 'Search for products with a search bar', - 'search-products', + 'Fetch a single product by ID', + 'fetch-product-with-id', ), + description: + 'Retrieve complete product information using a known product ID. This example uses `fetchProductWithId()` to get detailed product data including title, variants, and pricing, useful when you need to display or validate specific product information.', }, { codeblock: generateCodeBlockForProductSearchApi( - 'Fetch a specific product with a product ID', - 'fetch-product-with-id', + 'Fetch a single product variant by ID', + 'fetch-product-variant-with-id', ), + description: + 'Get detailed information about a specific product variant using its variant ID. This example uses `fetchProductVariantWithId()` to retrieve variant-specific data like price, SKU, and inventory, useful for variant-level operations or displaying detailed variant information.', }, { codeblock: generateCodeBlockForProductSearchApi( - 'Fetch multiple products by specifying product IDs', - 'fetch-products-with-ids', + 'Fetch multiple product variants by IDs', + 'fetch-product-variants-with-ids', ), + description: + 'Retrieve multiple product variants at once by providing variant IDs. This example demonstrates using `fetchProductVariantsWithIds()` to efficiently fetch variant details for multiple items, ideal for bulk operations or displaying collections of variants.', }, { codeblock: generateCodeBlockForProductSearchApi( - 'Fetch a specific product variant with a variant ID', - 'fetch-product-variant-with-id', + 'Fetch multiple products by IDs', + 'fetch-products-with-ids', ), + description: + 'Retrieve multiple products simultaneously by providing an array of product IDs. This example shows how to use `fetchProductsWithIds()` to efficiently fetch several products in a single operation, reducing API calls and improving performance when working with product collections.', }, { codeblock: generateCodeBlockForProductSearchApi( - 'Fetch multiple product variants by specifying variant IDs', - 'fetch-product-variants-with-ids', + 'Fetch paginated variants for a product', + 'fetch-paginated-product-variants-with-product-id', ), + description: + 'Retrieve variants for a product with pagination support to handle products with many variants efficiently. This example shows how to use `fetchPaginatedProductVariantsWithProductId()` with pagination options, allowing you to load variants in manageable chunks and implement infinite scroll or load more functionality.', }, { codeblock: generateCodeBlockForProductSearchApi( - 'Fetch a page of product variants with a specific product ID', - 'fetch-paginated-product-variants-with-product-id', + 'Search for products with a search bar', + 'search-products', ), + description: + 'Implement product search with a SearchBar component to find products by text query. This example demonstrates using `search()` to perform real-time product searches, displaying results in a list as merchants type, enabling quick product discovery and selection.', }, ], }, + subSections: [ + { + type: 'Generic', + anchorLink: 'best-practices', + title: 'Best practices', + sectionContent: ` +- **Handle search results gracefully:** Check for undefined results and empty result sets. +- **Optimize search performance:** Consider caching frequently accessed product data and implementing debounced search to reduce API calls while users are typing search queries. +- **Provide relevant search options:** Use appropriate sorting options based on your use case—relevance for user searches, alphabetical for browsing, or recently added for highlighting new products. + `, + }, + { + type: 'Generic', + anchorLink: 'limitations', + title: 'Limitations', + sectionContent: ` +- Product search results are limited to products available on the current POS device and may not include the complete shop catalog if products aren't synced locally. +- Bulk operations (\`fetchProductsWithIds\` and \`fetchProductVariantsWithIds\`) are limited to 50 items maximum, with additional IDs automatically removed from requests. +- Search functionality depends on local product data synchronization and may not reflect real-time inventory or pricing changes until the next sync. + `, + }, + ], }; export default data; diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/scanner-api.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/scanner-api.doc.ts index 50c71e2be7..eba74208e1 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/scanner-api.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/scanner-api.doc.ts @@ -7,68 +7,83 @@ const generateCodeBlockForScannerApi = (title: string, fileName: string) => const data: ReferenceEntityTemplateSchema = { name: 'Scanner API', - description: ` -The Scanner API enables an extension to access scanner data and available scanning sources supported by the device. - -#### Supporting targets -- ${TargetLink.PosHomeModalRender} -- ${TargetLink.PosPurchasePostActionRender} -- ${TargetLink.PosProductDetailsActionRender} -- ${TargetLink.PosOrderDetailsActionRender} -- ${TargetLink.PosDraftOrderDetailsActionRender} -- ${TargetLink.PosCustomerDetailsActionMenuItemRender} -`, + description: + 'The Scanner API provides access to barcode and QR code scanning functionality on POS devices, allowing you to subscribe to scan events, monitor available scanner sources, and process scanned data through subscription callbacks. The API enables integration with device cameras, external scanners, and embedded scanning hardware.', isVisualComponent: false, type: 'APIs', definitions: [ { title: 'ScannerApi', - description: '', + description: + 'The `ScannerApi` object provides access to scanning functionality and scanner source information. Access these properties through `api.scanner` to monitor scan events and available scanner sources.', type: 'ScannerApiContent', }, ], - category: 'APIs', + category: 'Target APIs', + subCategory: 'Platform APIs', related: [], examples: { - description: 'Examples of receiving updates from the Scanner API', + description: + 'Learn how to handle barcode and QR code scans from cameras, external scanners, and embedded hardware.', examples: [ { codeblock: generateCodeBlockForScannerApi( - 'Subscribe to scan event updates', - 'subscribable-events', + 'Adapt UI to available scanner types', + 'conditional-scanner-example', + ), + description: + 'Adapt your scanning interface based on available hardware capabilities. This example shows how to conditionally render appropriate scanning UI for different device types—using camera scanning on devices with cameras while falling back to embedded scanning on devices like POS GO that lack camera hardware, ensuring a functional experience across all POS devices.', + }, + { + codeblock: generateCodeBlockForScannerApi( + 'Add products from hardware scanner', + 'hardware-scanner-example', ), + description: + 'Automatically add products to the cart when barcodes are scanned using external hardware scanners. This example listens for scan events and uses the scanned data to search for and add matching products, creating a seamless scanning workflow that works with physical scanners connected to the POS device.', }, { codeblock: generateCodeBlockForScannerApi( - 'Receiving updates on available scanner sources', + 'Monitor available scanner hardware', 'subscribable-sources', ), + description: + 'Subscribe to scanner source changes to detect which scanning methods are available on the device. This example demonstrates tracking available scanner sources (camera, external, embedded) in real time, allowing you to adapt your UI and functionality based on hardware capabilities.', }, - ], - exampleGroups: [ { - title: 'Use cases', - examples: [ - { - description: - 'In this example, assuming a physical scanner is connected to the POS, any scans performed when ui extensions are in use will automatically add the product to the cart if the data exists on the shop.', - codeblock: generateCodeBlockForScannerApi( - 'Hardware scanner example', - 'hardware-scanner-example', - ), - }, - { - description: - 'There might be situations where a developer needs to conditionally render UI elements based on the available scanning sources of the device on which the extension is installed. For example, an extension could be designed for full-screen camera scanning, but a device like POS GO does not have a camera. In such cases, it would be necessary to avoid rendering the camera scanner component and instead create a UI that supports embedded scanning.', - codeblock: generateCodeBlockForScannerApi( - 'Conditional scanner source rendering example', - 'conditional-scanner-example', - ), - }, - ], + codeblock: generateCodeBlockForScannerApi( + 'Subscribe to scan events', + 'subscribable-events', + ), + description: + 'Subscribe to scan events to process barcode and QR code data as it arrives. This example shows how to listen for scans from any available scanner source (camera, external scanner, or embedded hardware), enabling you to add products to cart, look up information, or trigger custom workflows based on scanned codes.', }, ], }, + subSections: [ + { + type: 'Generic', + anchorLink: 'best-practices', + title: 'Best practices', + sectionContent: ` +- **Manage subscriptions carefully:** Remember that \`RemoteSubscribable\` supports only one subscription at a time. If you need multiple subscriptions, use \`makeStatefulSubscribable\` or manage subscription cleanup to avoid conflicts. +- **Validate scanned data appropriately:** Validate scanned data before processing, implementing proper error handling for invalid codes, unsupported formats, or scanning errors. +- **Provide clear scanning feedback:** Give users clear feedback about scan results, including success confirmations, error messages, and guidance when scans fail or produce invalid data. +- **Adapt to available scanner sources:** Check available scanner sources and adapt your interface accordingly. + `, + image: 'camera-scanner-best-practice.png', + }, + { + type: 'Generic', + anchorLink: 'limitations', + title: 'Limitations', + sectionContent: ` +- The Scanner API is only available in action (modal) targets where scanning functionality is supported and can't be used in other targets. +- \`RemoteSubscribable\` supports only one subscription at a time. Use \`makeStatefulSubscribable\` if you need multiple components to subscribe to scan events simultaneously. +- Scanning availability depends on device hardware capabilities and may vary between different POS devices and configurations. + `, + }, + ], }; export default data; diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/session-api.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/session-api.doc.ts index e28619c9f0..2d230ff2f4 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/session-api.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/session-api.doc.ts @@ -7,29 +7,56 @@ const generateCodeBlockForSessionApi = (title: string, fileName: string) => const data: ReferenceEntityTemplateSchema = { name: 'Session API', description: - 'The Session API contains the information about the current user session, and allows to fetch a fresh session token for communication with your apps backend service.', + 'The Session API provides access to current POS session information and secure authentication tokens, allowing you to retrieve shop details, user information, location data, and generate tokens for secure backend communication. The API includes both static session data and dynamic token generation for authenticated API calls.', isVisualComponent: false, type: 'APIs', definitions: [ { title: 'SessionApi', - description: '', + description: + 'The `SessionApi` object provides access to current session information and authentication methods. Access these properties and methods through `api.session` to retrieve shop data and generate secure tokens. These methods enable secure API calls while maintaining user privacy and [app permissions](https://help.shopify.com/manual/your-account/users/roles/permissions/store-permissions#apps-and-channels-permissions).', type: 'SessionApiContent', }, ], - category: 'APIs', + category: 'Target APIs', + subCategory: 'Standard APIs', related: [], examples: { - description: 'Examples of using the Session API', + description: + 'Learn how to access session information and generate secure authentication tokens for backend communication.', examples: [ { codeblock: generateCodeBlockForSessionApi( - 'Retrieve the current session data', + 'Access shop and location information', 'token', ), + description: + 'Retrieve current session data including shop domain, location ID, and user information. This example shows how to access session properties to get shop context, enabling you to personalize experiences, make location-specific decisions, or pass shop identifiers to backend services.', }, ], }, + subSections: [ + { + type: 'Generic', + anchorLink: 'best-practices', + title: 'Best practices', + sectionContent: ` +- **Use appropriate identifiers:** Distinguish between \`userId\` (authenticated account) and \`staffMemberId\` (pinned staff member) to implement correct permissions and personalization logic. +- **Implement location-aware features:** Use \`locationId\` information. +- **Secure backend communication:** Use session tokens exclusively for backend API calls and never expose them in client-side logs or storage. Validate tokens on your backend before processing requests. + `, + }, + { + type: 'Generic', + anchorLink: 'limitations', + title: 'Limitations', + sectionContent: ` +- Session tokens are only available when the authenticated user has proper app permissions enabled. Staff members who are pinned in but not authenticated can't generate tokens. +- Session data is read-only and can't be modified through the API. Changes to shop settings, locations, or staff assignments require POS application updates. +- Session tokens should only be used for communication with your app's configured backend service and can't be used for direct Shopify API calls from the client side. + `, + }, + ], }; export default data; diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/toast-api.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/toast-api.doc.ts index d3bfa7dfab..d783462430 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/toast-api.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/toast-api.doc.ts @@ -6,29 +6,57 @@ const generateCodeBlockForToastApi = (title: string, fileName: string) => const data: ReferenceEntityTemplateSchema = { name: 'Toast API', - description: 'The Toast API allows the display of a Toast component.', + description: + "The Toast API provides temporary notification functionality for POS UI extensions, allowing you to display brief, non-intrusive messages to users for feedback, confirmations, and status updates that automatically disappear after a specified duration. Toast messages appear as overlay notifications that don't interrupt the user's workflow.", isVisualComponent: false, type: 'APIs', definitions: [ { title: 'ToastApi', - description: '', + description: + 'The `ToastApi` object provides methods for displaying temporary notification messages. Access these methods through `api.toast` to show user feedback and status updates.', type: 'ToastApiContent', }, ], - category: 'APIs', + category: 'Target APIs', + subCategory: 'Standard APIs', related: [], examples: { - description: 'Examples of using the Toast API', + description: + 'Learn how to display temporary notification messages for user feedback, confirmations, and status updates.', examples: [ { codeblock: generateCodeBlockForToastApi( - 'Display a Toast component from the tile', + 'Show a toast notification', 'show', ), + description: + "Display a brief, non-intrusive notification message that automatically dismisses. This example demonstrates using `toast.show()` to provide immediate feedback after user actions, confirmations for successful operations, or status updates without interrupting the merchant's workflow.", }, ], }, + subSections: [ + { + type: 'Generic', + anchorLink: 'best-practices', + title: 'Best practices', + sectionContent: ` +- **Use appropriate timing:** Choose duration values that give users enough time to read the message without keeping notifications visible longer than necessary. +- **Provide meaningful feedback:** Use toast messages to confirm successful actions, explain errors clearly, or communicate important status changes that users need to know about. +- **Avoid overuse:** Reserve toast notifications for important feedback and avoid showing multiple toasts simultaneously, as this can overwhelm users and reduce the effectiveness of the notifications. + `, + }, + { + type: 'Generic', + anchorLink: 'limitations', + title: 'Limitations', + sectionContent: ` +- Toast messages are temporary and can't be made persistent. For important information that users need to reference later, consider using other UI components or storage mechanisms. +- Multiple toast messages may overlap or interfere with each other if shown in rapid succession. Consider queuing or spacing out notifications appropriately. +- Toast content is limited to plain text and can't include rich formatting, links, or interactive elements. + `, + }, + ], }; export default data; diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/ActionItem.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/ActionItem.doc.ts index ec5c81fb9d..7092f77f72 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/ActionItem.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/ActionItem.doc.ts @@ -20,16 +20,40 @@ const data: ReferenceEntityTemplateSchema = { type: 'ActionItemProps', }, ], - category: 'Components', + category: 'UI components', + subCategory: 'Actions', related: [], thumbnail: 'action-item-thumbnail.png', defaultExample: { image: 'action-item-default.png', codeblock: generateCodeBlockForActionItem( - 'Render an ActionItem in post purchase', + 'Show a post-purchase action menu item', 'default.example', ), + description: + 'Display an action menu item in the post-purchase flow. This example shows how to render an ActionItem that appears in action menus, providing merchants with a tappable entry point to launch your extension after a transaction is completed.', }, + subSections: [ + { + type: 'Generic', + anchorLink: 'best-practices', + title: 'Best practices', + sectionContent: ` +- **Control availability with enabled state:** Use the \`enabled\` property to control when a component can be tapped based on context. Set a component's \`enabled\` property to \`false\` when the extension's functionality isn't applicable to the current state. For example, if your extension applies a discount for new customers, set \`enable\` to \`false\` when processing a purchase for an existing customer. +- **Maintain consistent interaction patterns:** Follow established POS interaction patterns by using \`ActionItem\` components primarily with the \`api.action.presentModal()\` method as entry points to modal workflows. This creates predictable user experiences that align with merchant expectations and standard POS behaviors. +- **Handle errors and edge cases:** Implement proper error handling in \`onPress\` callbacks to manage network failures, invalid data states, or other exceptional conditions. Provide meaningful feedback to merchants when operations cannot be completed. + `, + }, + { + type: 'Generic', + anchorLink: 'limitations', + title: 'Limitations', + sectionContent: ` +- \`ActionItem\` components can only be used within supported action menu-item targets. They can't be rendered in action (modal) or block targets. +- Multiple \`ActionItem\` components from the same app can't be rendered simultaneously on the same target. Each extension can only contribute one \`ActionItem\` for each supported target. + `, + }, + ], }; export default data; diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/Badge.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/Badge.doc.ts index f7e690fa13..82bfef6c3b 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/Badge.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/Badge.doc.ts @@ -7,47 +7,50 @@ const generateCodeBlockForBadge = (title: string, fileName: string) => const data: ReferenceEntityTemplateSchema = { name: 'Badge', description: - 'Badges are used to inform merchants of the status of an item or action that’s been taken.', + 'The `Badge` component uses color and text to communicate status information for orders, products, customers, and other business data. Use badges to create visual hierarchy and help merchants quickly identify important information or status changes within your POS interface.\n\nThe component automatically adjusts its appearance based on the specified `tone` property, ensuring consistent visual communication across the POS interface. Badges support different sizes and can display text, numbers, or status indicators, making them versatile for representing everything from order counts to inventory alerts in a compact, scannable format.', isVisualComponent: true, type: 'component', definitions: [ { - title: 'Badge', - description: '', + title: 'Properties', + description: + 'Configure the following properties on the `Badge` component.', type: 'BadgeProps', }, ], - category: 'Components', + category: 'UI components', + subCategory: 'Feedback and status indicators', related: [], thumbnail: 'badge-thumbnail.png', defaultExample: { image: 'badge-default.png', - codeblock: generateCodeBlockForBadge('Badge', 'default.example'), + codeblock: generateCodeBlockForBadge( + 'Show a status badge', + 'default.example', + ), + description: + 'Show status information using color-coded badges. This example demonstrates rendering badges with different variants (success, warning, critical, info) and status indicators to communicate order, product, or customer status at a glance.', }, subSections: [ { type: 'Generic', - anchorLink: 'guidelines', - title: 'Guidelines', + anchorLink: 'best-practices', + title: 'Best practices', sectionContent: ` -- Badges should be positioned as close as possible to the item they’re related to. -`, +- **Keep badge text concise and clear:** Badge text should be brief and immediately understandable. Use single words when possible, or short phrases for complex states. Avoid lengthy descriptions that might not fit well within the badge's compact design. +- **Position badges close to related content:** Place badges near the items they describe to create clear associations. For example, position order status badges next to order numbers, or inventory badges next to product names to maintain visual relationships. +- **Maintain consistency across similar contexts:** Use the same badge variants and terminology for similar states throughout your POS interface. This helps merchants develop familiarity with your status system and reduces cognitive load when processing information. +- **Use badges for status, not actions:** Badges are designed to display information and status, not to trigger actions. For interactive elements, use buttons or clickable components instead of badges to maintain clear interaction patterns. + `, }, { type: 'Generic', - anchorLink: 'content-guidelines', - title: 'Content guidelines', + anchorLink: 'limitations', + title: 'Limitations', sectionContent: ` -- Be concise. Use a single word to describe the status of an item. -- Only use two or three words if you need to describe a complex state, for example "partially fulfilled". - -✅ fulfilled -❌ order fulfilled - -Statuses should ideally be written as adjectives: - -✅ unpaid -❌ payment not received +- Badges aren't interactive elements—they display information but don't respond to user interactions like clicks or taps. +- The component relies on predefined variants for styling, so custom appearances may require different approaches. +- Very long text content may be truncated or cause layout issues depending on the container and screen size. `, }, ], diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/Banner.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/Banner.doc.ts index b0395da24a..cb02733049 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/Banner.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/Banner.doc.ts @@ -7,32 +7,51 @@ const generateCodeBlockForBanner = (title: string, fileName: string) => const data: ReferenceEntityTemplateSchema = { name: 'Banner', description: - 'A banner informs merchants about important changes or persistent conditions. Use if you need to communicate to merchants in a prominent way, without blocking other actions.', + 'The `Banner` component highlights important information or required actions prominently within the POS interface. Use banners to communicate critical updates, warnings, informational messages, or success notifications that require merchant attention in a persistent but non-interruptive way.\n\nThe component provides persistent visibility for important messages while remaining non-intrusive to the main workflow, with support for dismissible and non-dismissible states. It includes automatic color coding based on message severity and integrates with the POS design system to maintain visual consistency across different alert types and use cases.', isVisualComponent: true, type: 'component', definitions: [ { - title: 'Banner', - description: '', + title: 'Properties', + description: + 'Configure the following properties on the `Banner` component.', type: 'BannerProps', }, ], - category: 'Components', + category: 'UI components', + subCategory: 'Feedback and status indicators', related: [], thumbnail: 'banner-thumbnail.png', defaultExample: { image: 'banner-default.png', - codeblock: generateCodeBlockForBanner('Banner', 'default.example'), + codeblock: generateCodeBlockForBanner( + 'Show an information banner', + 'default.example', + ), + description: + 'Show a persistent informational message using a banner. This example demonstrates rendering a banner with different status variants (info, success, warning, critical) to communicate important information to merchants without interrupting their workflow.', }, subSections: [ { type: 'Generic', - anchorLink: 'guidelines', - title: 'Guidelines', + anchorLink: 'best-practices', + title: 'Best practices', sectionContent: ` -- Use when needing to communicate to merchants in a way that is persistent but non-interruptive. -- Only one banner should be visible at a time. -`, +- **Keep banner content concise and actionable:** Banner titles should be brief and clearly communicate the main message. If additional detail is needed, consider providing it through the action button or in a subsequent screen. Avoid overwhelming merchants with too much information in a single banner. +- **Manage banner visibility thoughtfully:** Use the \`visible\` property to control when banners appear and disappear. Show banners when relevant conditions occur and hide them once the situation is resolved or acknowledged. Avoid leaving stale banners visible that no longer apply to the current context. +- **Provide clear actions when needed:** When a banner requires user action, set \`hideAction\` to \`false\` and provide clear, actionable text for the action button. Make it obvious what steps merchants need to take to address the situation or get more information. +- **Handle banner interactions appropriately:** Implement meaningful \`onPress\` handlers that either resolve the banner's condition, provide more information, or guide merchants to the appropriate next steps. For simple informational banners, the default dismiss behavior may be sufficient. +- **Limit banner frequency:** Avoid showing multiple banners simultaneously or in rapid succession, as this can overwhelm the interface and reduce the effectiveness of important messages. Queue banners appropriately and prioritize critical messages. + `, + }, + { + type: 'Generic', + anchorLink: 'limitations', + title: 'Limitations', + sectionContent: ` +- Banners require explicit visibility management through the \`visible\` property—they don't automatically dismiss based on time or user actions unless programmed to do so. +- The action button functionality is limited to a single action per banner—complex workflows may require navigation to dedicated screens. + `, }, ], }; diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/Button.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/Button.doc.ts index 11785b4e8f..e18f28974d 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/Button.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/Button.doc.ts @@ -6,15 +6,15 @@ const generateCodeBlockForButton = (title: string, fileName: string) => const data: ReferenceEntityTemplateSchema = { name: 'Button', - description: `Buttons enable the merchant to initiate actions, like "add", "save", or "next". - > Note: - > The \`plain\` \`ButtonType\` is no longer supported as of POS 10.0.0 and defaults to \`basic\`.`, + description: + 'The `Button` component triggers actions or events, such as opening dialogs or navigating to other pages. Use `Button` to let merchants perform specific tasks or initiate interactions throughout the POS interface.\n\nButtons provide clear calls-to-action that guide merchants through workflows, enable form submissions, and trigger important operations. They support various visual styles, tones, and interaction patterns to communicate intent and hierarchy within the interface.', isVisualComponent: true, type: 'component', definitions: [ { - title: 'Button', - description: '', + title: 'Properties', + description: + 'Configure the following properties on the `Button` component.', type: 'ButtonProps', }, { @@ -23,16 +23,39 @@ const data: ReferenceEntityTemplateSchema = { type: 'ButtonType', }, ], - category: 'Components', + category: 'UI components', + subCategory: 'Actions', related: [], thumbnail: 'button-thumbnail.png', defaultExample: { image: 'button-default.png', - codeblock: generateCodeBlockForButton( - 'Render a button that presents a toast', - 'default.example', - ), + codeblock: generateCodeBlockForButton('Show a button', 'default.example'), + description: + 'Display a button that responds to user interactions. This example shows a button that displays a toast notification when pressed, demonstrating how to handle button taps and provide immediate feedback to merchants.', }, + subSections: [ + { + type: 'Generic', + anchorLink: 'best-practices', + title: 'Best practices', + sectionContent: ` +- **Choose appropriate variants and tones:** Use \`primary\` variant for the most important action on a screen, \`secondary\` for supporting actions, and \`tertiary\` for less prominent options. Apply \`critical\` tone for destructive actions like "Delete order," \`success\` for positive actions like "Complete sale," and \`caution\` or \`warning\` for actions requiring attention. +- **Provide loading states for async operations:** Set the \`loading\` property to \`true\` during async operations. +- **Use the command system for component control:** Use \`commandFor\` and \`command\` properties to control modals, overlays, and other components without complex event handlers. +- **Structure button hierarchies clearly:** Place primary and secondary actions together using consistent spacing and visual hierarchy. Position destructive actions separately or use confirmation patterns to prevent accidental activation. + `, + }, + { + type: 'Generic', + anchorLink: 'limitations', + title: 'Limitations', + sectionContent: ` +- Button titles must be plain strings. HTML, markdown, or rich text formatting isn't supported. +- Loading states replace all button content with a spinner. Custom loading indicators or partial content updates aren't supported. +- Complex button layouts or nested interactive components within buttons aren't supported. + `, + }, + ], }; export default data; diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/CameraScanner.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/CameraScanner.doc.ts index aaaf14865f..92b7f61c63 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/CameraScanner.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/CameraScanner.doc.ts @@ -7,80 +7,51 @@ const generateCodeBlockForCameraScanner = (title: string, fileName: string) => const data: ReferenceEntityTemplateSchema = { name: 'CameraScanner', description: - 'The camera scanner uses the devices camera to scan and decode barcodes or QR codes. It displays a live feed with guidance markers for alignment and triggers actions within the app upon successful recognition.', + 'The `CameraScanner` component provides camera-based scanning functionality with optional banner messaging. Use it to enable barcode scanning, QR code reading, or other camera-based input methods with contextual user feedback.\n\n`CameraScanner` works in conjunction with the Scanner API to capture scan data from device cameras, providing both the visual interface and the data handling capabilities for complete scanning workflows.\n\n`CameraScanner` components provide real-time feedback during scanning operations with visual guides for optimal positioning, helping merchants quickly capture barcodes even in challenging lighting conditions or with damaged labels. The component provides audio feedback during scanning operations, confirming successful scans without requiring visual confirmation.', isVisualComponent: true, type: 'component', definitions: [ { - title: 'CameraScanner', - description: '', + title: 'Properties', + description: + 'Configure the following properties on the `CameraScanner` component.', type: 'CameraScannerProps', }, ], - category: 'Components', - related: [ - { - name: 'Scanner API', - subtitle: 'See how to retrieve updates with the Scanner API.', - url: '/api/pos-ui-extensions/apis/scanner-api#examples', - }, - ], + category: 'UI components', + subCategory: 'Navigation and content', + related: [], thumbnail: 'camera-scanner-thumbnail.png', defaultExample: { image: 'camera-scanner-default.png', codeblock: generateCodeBlockForCameraScanner( - 'Camera scanner and data text example', + 'Scan barcodes with the camera', 'default.example', ), + description: + 'Enable barcode and QR code scanning using the device camera. This example demonstrates a full-screen camera scanner with scan data display and banner messaging, showing how to integrate camera-based scanning into your workflow for product lookups or inventory management.', }, subSections: [ { type: 'Generic', anchorLink: 'best-practices', - title: 'Best Practices', + title: 'Best practices', sectionContent: ` -- Utilize the error banner to display scanning errors or unrecognized barcodes at the top of the camera view screen. -- After a successful scan, dismiss the full-screen camera view and display a secondary screen showcasing the intended outcome. -- The camera scanner UI can be adjusted to display the camera view on part of the screen while dedicating the remaining portion to other components. This can be useful for tasks like inventory management. -- In situations where scanning should not be allowed within a specific section of your application, use an error banner to inform merchants that scanning is not permitted on that screen and offer alternative areas where the scanning function can be performed. -- Use the error banner at the top of the screen to denote errors while scanning or when encountering an unrecognized barcode. -- Upon successful scanning of an item, display a ‘Toast’ component with a message such as "Item scanned" to indicate the outcome. Additionally, altering the screen contents can also be used to signal a successful scan. -`, +- **Implement proper post-scan workflow management:** After successful scanning, dismiss the full-screen camera view and display a secondary screen showcasing the intended outcome. Use the Toast API (\`toast.show()\`) with concise messages like "Item scanned" to confirm successful operations and consider altering screen content to signal completion. +- **Optimize camera view layout for multitasking:** Adjust the camera scanner UI to display the camera view on part of the screen while dedicating remaining space to other components. This approach is particularly useful for tasks like inventory management where users need to see both camera input and related information simultaneously. +- **Write effective banner content:** Keep banner messages concise with one to two short sentences maximum. Make banners dismissible unless they contain critical information or important steps merchants need to take. Use clear, actionable language that guides users toward successful scanning. +- **Coordinate with Toast API for success feedback:** Use the Toast API (\`toast.show()\`) for short confirmation messages after successful scans. Keep toast messages to three to four words maximum, avoid using them for error messages, and write them in noun + verb pattern. For example, "Item scanned" instead of "Your item has been scanned and added to your inventory count!". + `, image: 'camera-scanner-best-practice.png', }, { type: 'Generic', - anchorLink: 'content-guidelines', - title: 'Content guidelines', + anchorLink: 'limitations', + title: 'Limitations', sectionContent: ` -For banners: - -- Be concise. -- Keep to 1 or 2 short sentences. -- Be dismissible unless it contains critical information or an important step merchants need to take. - -Example: - -✅ Scanning not permitted on this screen. Go to {Section} to scan items.
-Dismiss (CTA)
-❌Error. - -✅ Barcode not recognized. Try scanning item again.
-Dismiss (CTA)
-❌ Didn’t work. - -For toasts: - -- Used for short messages to confirm an action. -- Never go over 3 or 4 words. -- Do not use for error messages. -- Should be used for success messages. -- Written in the pattern of noun + verb. - -Example: - -✅ Item scanned.
-❌ Your item has been scanned and added to your inventory count! +- \`CameraScanner\` requires device camera access and appropriate permissions—functionality is limited on devices without cameras or when permissions are denied. +- Banner messaging is the only built-in user feedback mechanism—complex scanning feedback or custom UI elements require additional components or external state management. +- The component handles basic camera functionality—advanced camera controls, image processing, or custom scanning algorithms aren't supported within the component itself. `, }, ], diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/DateField.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/DateField.doc.ts index 42734921c2..772b418b87 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/DateField.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/DateField.doc.ts @@ -4,33 +4,56 @@ import {generateCodeBlock} from '../helpers/generateCodeBlock'; const data: ReferenceEntityTemplateSchema = { name: 'DateField', description: - 'A component that enables users to open a dialog and select a date through a text input.', + 'The `DateField` component captures date input with a consistent interface for date selection and proper validation. Use it to collect date information in forms, scheduling interfaces, or data entry workflows.\n\n`DateField` components support both manual text entry and picker selection, giving merchants flexibility to choose their preferred input method based on personal preference and specific date entry scenarios.\n\nFor visual calendar-based selection, consider `DatePicker`. The component validates dates in real-time and provides clear error messages for invalid entries, preventing form submission errors and reducing the need for merchants to correct date inputs multiple times.', isVisualComponent: true, type: 'component', definitions: [ { - title: 'DateField', - description: '', + title: 'Properties', + description: + 'Configure the following properties on the `DateField` component.', type: 'DateFieldProps', }, ], - category: 'Components', + category: 'UI components', + subCategory: 'Forms', related: [], defaultExample: { image: 'date-field-default.png', - codeblock: generateCodeBlock('Date input', 'date-field', 'date-input'), + codeblock: generateCodeBlock( + 'Capture date input with validation', + 'date-field', + 'date-input', + ), + description: + 'Collect date information using a text-based input field with built-in validation. This example shows how to implement a DateField that supports both manual text entry and picker selection, providing merchants with flexible date input options for scheduling, filtering, or data entry tasks.', }, + thumbnail: 'date-field-thumbnail.png', subSections: [ { type: 'Generic', - anchorLink: 'guidelines', - title: 'Guidelines', + anchorLink: 'best-practices', + title: 'Best practices', sectionContent: ` -- Use a smart default date for common selections. +- **Use clear and specific labels:** Provide descriptive labels that indicate what date is being requested, such as "Delivery Date" or "Appointment Date" rather than generic "Date." This helps users understand the context and purpose of the field. +- **Provide helpful guidance with helpText:** Use the \`helpText\` property to explain date constraints, format expectations, or other requirements. For example, "Select a date within the next 30 days" or "Must be a future date." +- **Implement proper validation and error handling:** Use the \`error\` property to display validation messages when users enter invalid dates. Provide clear, actionable error messages that help users correct their input. +- **Handle date values consistently:** The field defaults to the current date when no value is provided. Update the \`value\` property in response to the \`onChange\` callback to maintain controlled component behavior and ensure predictable state management. +- **Use action buttons for enhanced functionality:** Use the \`action\` property to provide quick access to related functionality like "Clear Date," "Set to Today," or "Show Calendar." This enhances usability without cluttering the interface. +- **Differentiate between input and change callbacks:** Use \`onInput\` for immediate feedback like clearing validation errors as soon as users start typing. Reserve \`onChange\` for updating the field value when editing is complete. Never use \`onInput\` to update the \`value\` property. + `, + }, + { + type: 'Generic', + anchorLink: 'limitations', + title: 'Limitations', + sectionContent: ` +- \`DateField\` provides text-based date input—for calendar-style visual date selection, use the \`DatePicker\` component which offers an interactive calendar interface. +- The field defaults to the current date rather than being empty—if you need an empty initial state, explicitly set the \`value\` property to an empty string. +- Action buttons are limited to simple press callbacks—complex action workflows require custom implementation or additional components. `, }, ], - thumbnail: 'date-field-thumbnail.png', }; export default data; diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/DatePicker.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/DatePicker.doc.ts index b109c58f73..a806a07227 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/DatePicker.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/DatePicker.doc.ts @@ -7,23 +7,55 @@ const generateCodeBlockForDatePicker = (title: string, fileName: string) => const data: ReferenceEntityTemplateSchema = { name: 'DatePicker', - description: 'A component used to select a date through a dialog.', + description: + 'The `DatePicker` component allows merchants to select a specific date using a calendar-like picker interface. Use it to provide visual date selection with an intuitive calendar view for improved user experience.\n\n`DatePicker` offers a calendar-based alternative to direct text input. The calendar interface allows merchants to see dates in context of the full month, making it easier to select dates relative to specific days of the week or to visualize date ranges within a month view. For simple date entry when users know the exact date, use `DateField`.', isVisualComponent: true, type: 'component', definitions: [ { - title: 'DatePicker', - description: '', + title: 'Properties', + description: + 'Configure the following properties on the `DatePicker` component.', type: 'DatePickerProps', }, ], - category: 'Components', + category: 'UI components', + subCategory: 'Forms', related: [], thumbnail: 'date-picker-thumbnail.png', defaultExample: { image: 'date-picker-default.png', - codeblock: generateCodeBlockForDatePicker('DatePicker', 'default.example'), + codeblock: generateCodeBlockForDatePicker( + 'Select a date with a calendar', + 'default.example', + ), + description: + 'Enable date selection using an intuitive calendar interface. This example demonstrates a DatePicker that displays dates in a monthly calendar view, making it easier for merchants to select dates in context and visualize date relationships, ideal for scheduling or date range selection.', }, + subSections: [ + { + type: 'Generic', + anchorLink: 'best-practices', + title: 'Best practices', + sectionContent: ` +- **Manage visibility state with the tuple pattern:** Use the \`visibleState\` tuple to control when the picker is shown or hidden. This pattern ensures consistent visibility management. +- **Handle date selection with onChange:** Implement the \`onChange\` callback to capture selected dates and update your application state accordingly. This callback receives the selected date string that you can use to update UI or trigger related actions. +- **Provide clear triggers for showing the picker:** Since visibility is controlled by \`visibleState\`, ensure you have clear UI elements like buttons or field interactions that toggle the picker visibility. Users should understand how to open and close the date picker. +- **Default to current date thoughtfully:** The picker defaults to the current date when no \`selected\` value is provided. If you need a different starting date or want to guide users to a specific time period, explicitly set the \`selected\` property. +- **Optimize for touch interaction:** Both input modes are designed for touch interaction on POS devices. Ensure adequate spacing around trigger elements and consider how the picker overlay affects the overall interface layout. + `, + }, + { + type: 'Generic', + anchorLink: 'limitations', + title: 'Limitations', + sectionContent: ` +- \`DatePicker\` requires external visibility state management through the \`visibleState\` tuple—automatic show/hide behavior based on field focus isn't built-in. +- The component provides date selection but doesn't include field labels, help text, or error messaging—combine with other UI elements or text components to provide complete form field experiences. +- Input mode determines the interaction pattern but can't be changed dynamically while the picker is visible—you must set the mode before displaying the picker. + `, + }, + ], }; export default data; diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/Dialog.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/Dialog.doc.ts index e791376cf7..70c27ac062 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/Dialog.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/Dialog.doc.ts @@ -7,64 +7,52 @@ const generateCodeBlockForDialog = (title: string, fileName: string) => const data: ReferenceEntityTemplateSchema = { name: 'Dialog', description: - 'A dialog is a high-priority, intentionally disruptive message that requires action from the merchant before they can continue using POS.', + 'The `Dialog` component displays a modal that requires user attention and interaction. Use dialogs to present important information, confirm actions, or collect input from merchants in a focused overlay that interrupts the current workflow until resolved.\n\nThe component creates a modal overlay that focuses user attention on important decisions or information, blocking interaction with underlying content until dismissed. It supports various configurations including alert dialogs, confirmation dialogs, and custom content dialogs, with built-in button layouts and keyboard shortcuts for efficient navigation and decision-making.\n\n`Dialog` components provide customizable button layouts and keyboard shortcuts that follow platform conventions, ensuring merchants can quickly approve or dismiss dialogs through familiar interaction patterns.', isVisualComponent: true, type: 'component', definitions: [ { - title: 'Dialog', - description: '', + title: 'Properties', + description: + 'Configure the following properties on the `Dialog` component.', type: 'DialogProps', }, ], - category: 'Components', + category: 'UI components', + subCategory: 'Feedback and status indicators', related: [], thumbnail: 'dialog-thumbnail.png', defaultExample: { image: 'dialog-default.png', - codeblock: generateCodeBlockForDialog('Dialog example', 'default.example'), + codeblock: generateCodeBlockForDialog( + 'Show a confirmation dialog', + 'default.example', + ), + description: + 'Present important information or confirmations that require user attention. This example demonstrates a Dialog that overlays the interface to display alerts, confirmations, or input prompts with customizable buttons and actions, blocking interaction until merchants respond.', }, subSections: [ { type: 'Generic', - anchorLink: 'guidelines', - title: 'Guidelines', + anchorLink: 'best-practices', + title: 'Best practices', sectionContent: ` -- A dialog appears on top of the view the merchant is currently looking at. -- When a dialog appears, the merchant can only interact with the buttons in the dialog and nothing else in the view. -- A scrim is used to dim the UI in the background, using the surfaceBackground color set to 60% transparency. -- Dialogs always include at least one action, two actions at most. -- Buttons in dialogs work best when stacked to accommodate for longer translated content. -- When buttons are displayed side-by-side, the primary action is on the right. When buttons are stacked, the primary action is at the top. -- For buttons that initiate irreversible actions, the text should be displayed in "destructive" (red) state. -`, +- **Write clear, concise content:** Use brief, action-oriented titles and essential context without overwhelming users. +- **Use meaningful button text:** Use specific text like "Delete Order" and "Keep Order" rather than generic "OK" and "Cancel." +- **Frame confirmations as questions:** For confirmations, use questions like "Delete this order?" rather than "Are you sure?" +- **Use destructive type for irreversible actions:** Set \`destructive\` for deletions to display red buttons as visual warnings. +- **Use "OK" for informational dialogs:** For acknowledgment-only dialogs, use a single "OK" button. +- **Structure error dialogs effectively:** Use the header to communicate the problem, body and button to communicate the solution. + `, }, { type: 'Generic', - anchorLink: 'content-guidelines', - title: 'Content guidelines', + anchorLink: 'limitations', + title: 'Limitations', sectionContent: ` -For confirmation dialogs, the header should be formed as a question that re-emphasizes the action being taken. Don't write: "Are you sure?" - -✅ Log out of Shopify POS?
-❌ Are you sure you want to log out of Shopify POS?
-❌ You’re about to log out of Shopify POS - -For confirmation dialogs, the primary button should clearly confirm the action while the secondary button should cancel the action with "Cancel": - -✅ [Primary button] Log out
-❌ [Primary button] Yes - -For errors, the header should clearly communicate the problem rather than the solution (use the body and button to communicate the solution): - -✅ [Header] Transaction declined
-❌ [Header] Retry transaction - -For informational dialogs where there's no action for the merchant to take but to acknowledge the message, the sole button should be "OK": - -✅ [Button] OK
-❌ [Button] Understood
-❌ [Button] Dismiss +- Content space is limited, so keep dialog text concise and avoid lengthy explanations that might not fit properly on smaller POS displays. +- Dialogs require explicit visibility management through the \`isVisible\` property and don't automatically dismiss based on time or external events. +- Multiple dialogs can't be displayed simultaneously—showing a new dialog while another is visible may cause unexpected behavior. `, }, ], diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/EmailField.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/EmailField.doc.ts index 5c3f7b75a2..706a45f0a3 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/EmailField.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/EmailField.doc.ts @@ -4,22 +4,56 @@ import {generateCodeBlock} from '../helpers/generateCodeBlock'; const data: ReferenceEntityTemplateSchema = { name: 'EmailField', description: - 'Use an email field to conveniently and accurately capture merchant email addresses.', + 'The `EmailField` component captures email address input from customers with built-in validation. Use it to collect email information in forms, customer profiles, or contact workflows.\n\nThe component includes built-in email format validation using standard email patterns to ensure data quality. It provides real-time feedback on invalid entries and supports features like autocomplete and keyboard optimization for email input, helping merchants quickly capture valid customer contact information during checkout or registration workflows.\n\n`EmailField` components integrate with browser autocomplete features to speed up email entry by suggesting previously used addresses, significantly reducing typing time during customer registration workflows.', isVisualComponent: true, type: 'component', definitions: [ { - title: 'EmailField', - description: '', + title: 'Properties', + description: + 'Configure the following properties on the `EmailField` component.', type: 'EmailFieldProps', }, ], defaultExample: { - codeblock: generateCodeBlock('Email input', 'email-field', 'email-input'), + image: 'email-field-default.png', + codeblock: generateCodeBlock( + 'Capture email input with validation', + 'email-field', + 'email-input', + ), + description: + 'Capture customer email addresses with built-in format validation. This example shows how to implement an EmailField that validates email syntax in real-time, provides autocomplete support, and optimizes the keyboard for email entry, ensuring accurate customer contact information.', }, - category: 'Components', + category: 'UI components', + subCategory: 'Forms', related: [], thumbnail: 'email-field-thumbnail.png', + subSections: [ + { + type: 'Generic', + anchorLink: 'best-practices', + title: 'Best practices', + sectionContent: ` +- **Provide helpful guidance with placeholder and helpText:** Use placeholder text for format examples like \`customer@example.com\` and the \`helpText\` property for additional context like "Required for digital receipts" or "We'll send order updates to this address." +- **Implement proper email validation:** Use the \`error\` property to display validation messages when users enter invalid email formats. Provide clear, actionable error messages like "Please enter a valid email address" that help users correct their input. +- **Use the email-optimized keyboard:** \`EmailField\` automatically display the email-optimized keyboard on mobile devices with easy access to \`@\` and domain symbols. This improves input speed and reduces errors on touch devices. +- **Use the required property appropriately:** Set \`required\` to \`true\` for fields that must have a value. While this adds semantic meaning, you must still implement validation logic and use the \`error\` property to display validation errors to users. +- **Add action buttons for enhanced functionality:** Use the \`action\` property to provide helpful actions like "Validate Email," "Use Default Email," or "Clear Field." This enhances usability by providing quick access to common operations. +- **Differentiate between input and change callbacks:** Use \`onInput\` for immediate feedback like clearing validation errors as soon as users start typing. Reserve \`onChange\` for updating the field value when editing is complete. Never use \`onInput\` to update the \`value\` property. + `, + }, + { + type: 'Generic', + anchorLink: 'limitations', + title: 'Limitations', + sectionContent: ` +- \`EmailField\` provides the input interface but doesn't perform automatic email validation—you must implement validation logic and use the \`error\` property to display validation results. +- The \`required\` property adds semantic meaning only—it doesn't trigger automatic error display or prevent form submission without additional validation logic. +- Action buttons are limited to simple press callbacks—complex action workflows require custom implementation or additional components. + `, + }, + ], }; export default data; diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/FormattedTextField.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/FormattedTextField.doc.ts index 6c8ede5983..18f7a2b31f 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/FormattedTextField.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/FormattedTextField.doc.ts @@ -7,7 +7,7 @@ const generateCodeBlockForComponent = (title: string, fileName: string) => const data: ReferenceEntityTemplateSchema = { name: 'FormattedTextField', description: - 'Use a formatted text field when you require additional functionality such as the text field input type or a custom validator.', + 'The `FormattedTextField` component captures text input with specific formatting, validation, and keyboard optimization. Use it to collect formatted text with appropriate input types and auto-capitalization rules.\n\nThe component applies real-time formatting as users type, supporting patterns like phone numbers, credit cards, postal codes, and custom formats through configurable masks. It maintains separate formatted display and raw value states, ensuring that validation and data submission use clean unformatted values while providing user-friendly formatted display during input.\n\n`FormattedTextField` components prevents invalid character entry at the input level rather than validation after entry, providing immediate feedback and reducing the frustration of correcting masked input patterns.', isVisualComponent: true, type: 'component', definitions: [ @@ -27,16 +27,43 @@ const data: ReferenceEntityTemplateSchema = { type: 'AutoCapitalizationType', }, ], - category: 'Components', + category: 'UI components', + subCategory: 'Forms', related: [], thumbnail: 'formatted-text-field-thumbnail.png', defaultExample: { image: 'formatted-text-field-default.png', codeblock: generateCodeBlockForComponent( - 'Render a FormattedTextField that validates email addresses', + 'Capture formatted text input', 'default.example', ), + description: + 'Collect text input with specific formatting patterns and validation rules. This example demonstrates a FormattedTextField that applies real-time formatting as users type, supports custom input masks, and optimizes keyboard types for different data formats like phone numbers or postal codes.', }, + subSections: [ + { + type: 'Generic', + anchorLink: 'best-practices', + title: 'Best practices', + sectionContent: ` +- **Apply auto-capitalization based on content type:** Use \`'sentences'\` for prose or descriptions, \`'words'\` for names and titles, \`'characters'\` for codes or identifiers that should be uppercase, and \`'none'\` when capitalization should be controlled by the user. +- **Manage validation with isValid and errorMessage:** Set \`isValid\` to false and provide a clear \`errorMessage\` when input doesn't meet requirements. Update these properties as users type to provide immediate feedback about validation status. +- **Use initialValue for pre-populated fields:** Set \`initialValue\` when editing existing data or providing default values. This helps users by reducing the amount of typing required and providing context for expected input. +- **Provide helpful placeholder text:** Use placeholder text to show input format examples, especially for specialized input types like currency ("$0.00"), gift cards ("XXXX-XXXX-XXXX"), or email (\`user@example.com\`). +- **Implement real-time validation with onChangeText:** Use the \`onChangeText\` callback to validate input as users type, providing immediate feedback and preventing invalid submissions. Update \`isValid\` and \`errorMessage\` based on validation results. + `, + }, + { + type: 'Generic', + anchorLink: 'limitations', + title: 'Limitations', + sectionContent: ` +- \`FormattedTextField\` provides keyboard optimization and basic validation UI but doesn't perform automatic formatting—you must implement formatting logic in your \`onChangeText\` callback for currency, phone numbers, or other formatted values. +- The \`isValid\` property controls visual styling only—it doesn't prevent form submission or enforce validation automatically, requiring custom validation logic. +- Input types optimize the keyboard layout but don't enforce format restrictions—users can still enter any characters, so validation in \`onChangeText\` is essential. + `, + }, + ], }; export default data; diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/Icon.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/Icon.doc.ts index 9eb597fc3b..e669f281e6 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/Icon.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/Icon.doc.ts @@ -3,40 +3,50 @@ import {generateCodeBlock} from '../helpers/generateCodeBlock'; const data: ReferenceEntityTemplateSchema = { name: 'Icon', - description: 'A component that renders an icon from the POS asset catalog.', + description: + 'The `Icon` component displays standardized visual symbols from the POS catalog to represent actions, statuses, or categories consistently. Use icons to enhance navigation or provide visual context alongside text in POS interfaces.\n\nIcons help merchants quickly understand interface elements and actions without relying solely on text labels. Icons are optimized for readability at standard sizes and automatically scale to maintain visual consistency across different screen densities and device types.', isVisualComponent: true, type: 'component', definitions: [ { - title: 'Icon', - description: '', + title: 'Properties', + description: + 'Configure the following properties on the `Icon` component.', type: 'IconProps', }, ], - category: 'Components', - related: [ + category: 'UI components', + subCategory: 'Media and visuals', + related: [], + defaultExample: { + image: 'icon-default.png', + codeblock: generateCodeBlock('Show icons', 'icon', 'default-example'), + description: + 'Show icons from the POS catalog to represent actions or statuses consistently. This example demonstrates rendering icons that enhance navigation, provide visual context alongside text, and maintain visual consistency across the interface with automatic scaling for different screen densities.', + }, + thumbnail: 'icon-thumbnail.png', + subSections: [ { - name: 'Figma UI Kit', - subtitle: - 'See the Figma UI Kit to get a full list of icons to design your extension', - url: 'https://www.figma.com/community/file/1493617217926107705', - type: 'star', + type: 'Generic', + anchorLink: 'best-practices', + title: 'Best practices', + sectionContent: ` +- **Use appropriate sizes for context:** Match icon sizes to their surrounding content and importance. Use \`'s'\` for inline text or secondary actions, \`'m'\` for standard interface elements, \`'l'\` (default) for primary actions, and \`'xl'\` for prominent features or headers. +- **Apply consistent tones for semantic meaning:** Use tone consistently across your interface to establish clear visual patterns. Apply \`'icon-critical'\` for destructive actions like delete, \`'icon-warning'\` for cautions, \`'icon-success'\` for confirmations, and \`'icon-primary'\` for general interface elements. +- **Combine icons with text when appropriate:** While icons enhance visual communication, consider pairing them with text labels, especially for complex or less common actions. + `, }, - ], - subSections: [ { type: 'Generic', - anchorLink: 'guidelines', - title: 'Guidelines', + anchorLink: 'limitations', + title: 'Limitations', sectionContent: ` -- Icons in POS are used in areas where they specifically add clarity and structure to the UI, aiding in creating a deeper understanding of the product and common interaction points nested throughout the experience.`, +- Icons are purely decorative and don't support click events or interactive behaviors. +- The available icon set is predefined and limited to POS-specific symbols—custom icons or external icon libraries aren't supported. +- Icon appearance and styling are controlled by the POS design system—custom colors, styles, or modifications beyond the provided properties are not available. + `, }, ], - defaultExample: { - image: 'icon-default.png', - codeblock: generateCodeBlock('Example icons', 'icon', 'default-example'), - }, - thumbnail: 'icon-thumbnail.png', }; export default data; diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/Image.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/Image.doc.ts index 35d0b44003..7bfe6da5cf 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/Image.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/Image.doc.ts @@ -4,23 +4,48 @@ import {generateCodeBlock} from '../helpers/generateCodeBlock'; const data: ReferenceEntityTemplateSchema = { name: 'Image', description: - 'The image component displays an image to a merchant in Shopify POS.', + 'The `Image` component adds visual content within the interface and allows you to customize the presentation of visuals. Use images to showcase products, illustrate concepts, provide visual context, or support user tasks and interactions in POS workflows.\n\nImages enhance the user experience by providing immediate visual recognition and reducing cognitive load.\n\n`Image` components handle loading errors gracefully with fallback options and provides placeholder states to maintain layout stability during image loading on slower network connections. The component implements lazy loading for images outside the viewport, improving initial page load performance while ensuring smooth scrolling as merchants navigate through product catalogs or image-heavy interfaces.', isVisualComponent: true, type: 'component', definitions: [ { - title: 'Image', - description: '', + title: 'Properties', + description: + 'Configure the following properties on the `Image` component.', type: 'ImageProps', }, ], - category: 'Components', + category: 'UI components', + subCategory: 'Media and visuals', related: [], defaultExample: { image: 'image-default.png', - codeblock: generateCodeBlock('Example image', 'image', 'default-example'), + codeblock: generateCodeBlock('Show an image', 'image', 'default-example'), + description: + 'Show images within your extension interface with customizable presentation. This example demonstrates rendering images with proper sizing, loading states, and error handling, ideal for showcasing products, illustrating concepts, or providing visual context in POS workflows.', }, thumbnail: 'image-thumbnail.png', + subSections: [ + { + type: 'Generic', + anchorLink: 'best-practices', + title: 'Best practices', + sectionContent: ` +- **Plan for loading states:** The component automatically shows placeholders during loading or when no \`src\` is provided. Design your layouts to accommodate these loading states and ensure they don't negatively impact the user experience. +- **Consider responsive design:** Test your image layouts on various POS devices. + `, + }, + { + type: 'Generic', + anchorLink: 'limitations', + title: 'Limitations', + sectionContent: ` +- Images are display-only components and don't support click events or interactive behaviors. +- Image loading and caching behavior depends on the browser and network conditions—implement proper error handling for better user experience. +- Large images can impact performance—ensure proper optimization and consider the device capabilities of your target POS hardware. + `, + }, + ], }; export default data; diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/List.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/List.doc.ts index 86a515ee20..5ba9862c8b 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/List.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/List.doc.ts @@ -3,60 +3,50 @@ import {generateCodeBlock} from '../helpers/generateCodeBlock'; const data: ReferenceEntityTemplateSchema = { name: 'List', - description: `The list is a scrollable component in which the list rows are rendered. - > Note: - > List items no longer have dividers as of POS 10.0.0.`, + description: + 'The `List` component displays structured data in rows with rich content including labels, subtitles, badges, images, and interactive elements. Use it to present organized information with consistent formatting and user interaction capabilities.\n\nList items no longer have dividers as of POS version 10.0.0.', isVisualComponent: true, type: 'component', definitions: [ { - title: 'List', - description: '', + title: 'Properties', + description: + 'Configure the following properties on the `List` component.', type: 'ListProps', }, ], - category: 'Components', - related: [ - { - name: 'ProductSearch API', - subtitle: - 'See how to use the ProductSearch API with a SearchBar to search for products.', - url: '/api/pos-ui-extensions/apis/productsearch-api#example-search-for-products-with-a-search-bar', - }, - ], + category: 'UI components', + subCategory: 'Layout and structure', + related: [], thumbnail: 'list-thumbnail.png', defaultExample: { image: 'list-default.png', - codeblock: generateCodeBlock('Product List', 'list', 'products'), + codeblock: generateCodeBlock('Show a product list', 'list', 'products'), + description: + 'Display structured data in organized rows with rich content. This example demonstrates a List component showing products with labels, subtitles, images, and interactive elements, providing consistent formatting for collections of items like products, customers, or menu options.', }, subSections: [ { type: 'Generic', - anchorLink: 'guidelines', - title: 'Guidelines', + anchorLink: 'best-practices', + title: 'Best practices', sectionContent: ` -List items have a wide variety of use cases: - -- To display and link to an object | Examples: an item in the cart, a customer in the customer list -- To display information | Examples: the payment breakdown in an order, staff contact information -- To display a menu item | Examples: an item on the first page of settings, an item in “More actions” -- To display a setting -- To display an action related to other items in the section -- To show a selectable option | Example: one filter option -- To display an external link - `, +- **Use images strategically with appropriate display strategies:** Choose the right image display strategy based on your content. Use \`'automatic'\` for mixed content, \`'always'\` when consistent image areas improve layout, and \`'never'\` for text-heavy lists where images would be distracting. +- **Implement efficient pagination with onEndReached:** Use the \`onEndReached\` callback to implement smooth pagination that doesn't disrupt the user experience. Set \`isLoadingMore\` appropriately to provide visual feedback during data fetching operations. +- **Apply semantic colors for subtitle information:** Use \`ColorType\` values in subtitles to convey meaning effectively. Apply \`TextSuccess\` for positive states, \`TextCritical\` for errors, and \`TextSubdued\` for less important information. +- **Design meaningful row interactions:** Use \`onPress\` callbacks for navigation or detail views, and \`showChevron\` to indicate navigation actions. Reserve toggle switches for immediate state changes that don't require navigation. +- **Optimize for touch interfaces:** Ensure adequate spacing and touch target sizes by leveraging the \`List\` component's built-in touch optimization. + `, }, { type: 'Generic', - anchorLink: 'content-guidelines', - title: 'Content Guidelines', + anchorLink: 'limitations', + title: 'Limitations', sectionContent: ` -Subtitles: - -- Each subtitle should have a different piece of information. Don't use dashes to display more than one type of information on the same line. -- Subtitles should be shown in order of relevance. -- If you're showing the results of the form, the label should be the form field title and the subtitle should be the information the merchant entered. - `, +- List row structure is predefined with specific left and right side layouts—custom row layouts beyond the provided structure aren't supported. +- Image display is limited to the left side of rows with optional badge overlays—complex image layouts or multiple images for each row aren't available. +- Toggle switches and interactive elements are limited to the predefined types—custom interactive components within rows require using \`onPress\` callbacks and external state management. + `, }, ], }; diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/Navigator.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/Navigator.doc.ts index 182365d190..cc6fda803b 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/Navigator.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/Navigator.doc.ts @@ -6,43 +6,77 @@ const generateCodeBlockForComponent = (title: string, fileName: string) => const data: ReferenceEntityTemplateSchema = { name: 'Navigator', - description: 'A component used to navigate between different screens.', + description: + 'The `Navigator` component manages navigation between multiple `Screen` components within a POS UI extension. Use it to create multi-screen workflows with proper navigation stack management and initial screen configuration.\n\n`Navigator` works with the Navigation API to provide complete navigation control for complex POS workflows that require multiple views and user interactions.\n\n`Navigator` components maintain navigation history across app lifecycle events and supports deep linking to specific screens, enabling merchants to return to their exact workflow state after interruptions The component supports gesture-based navigation like swipe-to-go-back on platforms where this is standard, providing familiar interaction patterns that feel native to each platform.', isVisualComponent: true, type: 'component', definitions: [ { - title: 'Navigator', - description: '', + title: 'Properties', + description: + 'Configure the following properties on the `Navigator` component.', type: 'NavigatorProps', }, ], - category: 'Components', + category: 'UI components', + subCategory: 'Navigation and content', related: [], thumbnail: 'navigator-thumbnail.png', defaultExample: { image: 'navigator-default.png', codeblock: generateCodeBlockForComponent( - 'Navigate to another screen', + 'Navigate between screens', 'navigate', ), + description: + 'Create a multi-screen navigation flow within your extension. This example shows how to set up a Navigator with multiple Screen components and navigate between them, enabling complex workflows, wizards, or detailed views with proper navigation stack management.', }, examples: { - description: 'Using a Navigator to navigate between Screens', + description: + 'Learn how to create multi-screen workflows with navigation, parameters, and different presentation styles.', examples: [ { codeblock: generateCodeBlockForComponent( - 'Navigate to another screen with parameters', + 'Pass data between screens', 'navigate-params', ), + description: + 'Navigate to screens while passing data as parameters. This example demonstrates how to send information from one screen to another using navigation parameters, enabling contextual data flow through multi-step workflows.', }, { codeblock: generateCodeBlockForComponent( - 'Navigate to another screen with sheet presentation', + 'Present a screen as a sheet', 'navigate-sheet', ), + description: + 'Show a screen using sheet presentation style for modal-like interactions. This example demonstrates how to present screens as overlays that slide up from the bottom, useful for quick actions or secondary information without losing the parent screen context.', }, ], }, + subSections: [ + { + type: 'Generic', + anchorLink: 'best-practices', + title: 'Best practices', + sectionContent: ` +- **Use descriptive screen names for navigation:** Choose clear, unique screen names that accurately represent their content and purpose. These names are used by the Navigation API for programmatic navigation and should be meaningful for code maintainability. +- **Set appropriate initial screens:** Select initial screens that provide the most logical entry point for your workflow. Consider the context in which your extension will be launched and what users will most likely want to see first. +- **Implement proper navigation patterns:** Use the Navigation API methods consistently—\`navigate()\` for moving forward, \`pop()\` for going back, and \`dismiss()\` for closing the extension. This creates predictable navigation behavior that users can understand. +- **Handle screen parameters effectively:** When passing parameters between screens using \`navigation.navigate()\`, ensure receiving screens properly handle the data through their \`onReceiveParams\` callbacks. Design parameter structures that are maintainable and type-safe. +- **Consider navigation context and user flow:** Design navigation patterns that make sense within the broader POS workflow. Avoid deep navigation hierarchies that might confuse users or disrupt their primary tasks. + `, + }, + { + type: 'Generic', + anchorLink: 'limitations', + title: 'Limitations', + sectionContent: ` +- \`Navigator\` requires \`Screen\` components as children—it can't manage navigation for other component types or standalone content. +- Navigation state is managed internally—external navigation state management or complex routing patterns require custom implementation using the Navigation API. +- The component is designed for modal-style navigation within POS UI extensions—it's not suitable for main application navigation or replacing core POS navigation patterns. + `, + }, + ], }; export default data; diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/NumberField.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/NumberField.doc.ts index 23267eaddb..d36e6ef6ee 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/NumberField.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/NumberField.doc.ts @@ -4,27 +4,54 @@ import {generateCodeBlock} from '../helpers/generateCodeBlock'; const data: ReferenceEntityTemplateSchema = { name: 'NumberField', description: - 'Use a number field to conveniently and accurately capture numerical values.', + 'The `NumberField` component captures numeric input with built-in validation. Use it to collect quantity, price, or other numeric information with proper validation.\n\nThe component includes built-in number validation, optional min/max constraints, and step increments to ensure accurate numeric data entry. It supports various number formats including integers and decimals, with validation feedback to prevent entry errors during high-volume retail operations.', isVisualComponent: true, type: 'component', definitions: [ { - title: 'NumberField', - description: '', + title: 'Properties', + description: + 'Configure the following properties on the `NumberField` component.', type: 'NumberFieldProps', }, ], - category: 'Components', + category: 'UI components', + subCategory: 'Forms', related: [], defaultExample: { image: 'number-field-default.png', codeblock: generateCodeBlock( - 'Number input', + 'Capture numeric input with validation', 'number-field', 'number-input', ), + description: + 'Collect numeric information using an optimized input field with built-in validation. This example shows how to implement a NumberField that validates numeric entries, supports optional min/max constraints, and provides step increments for quantities, prices, or other numeric data.', }, thumbnail: 'number-field-thumbnail.png', + subSections: [ + { + type: 'Generic', + anchorLink: 'best-practices', + title: 'Best practices', + sectionContent: ` +- **Select the right input mode for your data type:** Use \`'decimal'\` input mode for prices, measurements, or any values requiring decimal precision. Use \`'numeric'\` for quantities, counts, or integer values where decimal points aren't needed. This optimizes the keyboard layout for the expected input. +- **Provide helpful guidance with helpText:** Use the \`helpText\` property to explain numeric constraints, valid ranges, units, or formatting expectations. For example, "Enter a quantity between 1 and 999" or "Price in dollars with two decimal places." +- **Implement proper validation logic:** While \`min\`/\`max\` properties provide guidance, they don't prevent invalid keyboard input. Implement validation in your \`onChange\` callback to check bounds, format, and other requirements, then display errors using the \`error\` property. +- **Use action buttons for enhanced functionality:** Use the \`action\` property to provide helpful actions like "Clear Field," "Set to Minimum," or "Calculate Total." This enhances usability by providing quick access to common numeric operations. + `, + }, + { + type: 'Generic', + anchorLink: 'limitations', + title: 'Limitations', + sectionContent: ` +- \`NumberField\` provides numeric input but doesn't enforce \`min\`/\`max\` constraints for keyboard input—you must implement validation logic to enforce bounds and display appropriate errors. +- The \`required\` property adds semantic meaning only—it doesn't trigger automatic error display or prevent form submission without additional validation logic. +- Action buttons are limited to simple press callbacks—complex action workflows require custom implementation or additional components. + `, + }, + ], }; export default data; diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/POSBlock.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/POSBlock.doc.ts index 153b092315..32ae8177cd 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/POSBlock.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/POSBlock.doc.ts @@ -7,26 +7,55 @@ const generateCodeBlockForPOSBlock = (title: string, fileName: string) => const data: ReferenceEntityTemplateSchema = { name: 'POSBlock', description: - 'The `POSBlock` provides a surface on the specified extension target as an entry point to an extension. Note that the title displayed on this `POSBlock` is dependent on the description of the extension.', + 'The `POSBlock` component creates a container to place content with an action button. Use it to display structured content within POS block targets.\n\nThe component provides a standardized layout specifically designed for content blocks within POS detail views, with consistent padding, spacing, and optional action buttons. It integrates with the native POS design language, ensuring extension content feels cohesive with the core POS interface while maintaining clear content boundaries.\n\n`PosBlock` components provide consistent interaction patterns for action buttons across different block types, ensuring merchants can predict button behavior and location regardless of the specific POS context.', isVisualComponent: true, type: 'component', thumbnail: 'pos-block-thumbnail.png', definitions: [ { - title: 'POSBlock', - description: '', + title: 'Properties', + description: + 'Configure the following properties on the `POSBlock` component.', type: 'POSBlockProps', }, ], - category: 'Components', + category: 'UI components', + subCategory: 'Layout and structure', related: [], defaultExample: { image: 'pos-block-default.png', codeblock: generateCodeBlockForPOSBlock( - 'Render a POSBlock in post purchase', + 'Show content in a block container', 'default.example', ), + description: + 'Display structured content within POS block targets using a standardized container. This example demonstrates a POSBlock with consistent padding, spacing, and an optional action button, ensuring extension content feels cohesive with the core POS interface.', }, + subSections: [ + { + type: 'Generic', + anchorLink: 'best-practices', + title: 'Best practices', + sectionContent: ` +- **Design meaningful action buttons:** When providing an action, use clear and descriptive button titles that indicate exactly what will happen when pressed. Avoid generic terms like "Click here" in favor of specific actions like "View Details" or "Update Status." +- **Handle action states appropriately:** Use the disabled property to prevent user interaction when actions are not available or appropriate. Provide clear feedback through your extension's description or other UI elements when actions are disabled. +- **Design for the block context:** \`POSBlock\` appears within existing POS screens alongside other content. +- **Implement responsive action callbacks:** Consider showing loading states or confirmation messages when actions require network requests or significant processing time. +- **Maintain consistent action patterns:** Use similar action patterns across different \`POSBlock\` instances in your extension to create predictable user experiences. Consistent button titles and behaviors help merchants understand and trust your extension. + `, + }, + { + type: 'Generic', + anchorLink: 'limitations', + title: 'Limitations', + sectionContent: ` +- \`POSBlock\` is designed specifically for block targets—it can't be used in modal or action (menu item) targets. +- The component's visual styling and layout are controlled by the POS design system—custom styling isn't supported. +- Content display is determined by the extension's description rather than custom content properties—ensure your extension description is clear and informative. +- Only one action button is supported for each \`POSBlock\` instance to maintain clean, focused interfaces that integrate well with existing POS workflows. + `, + }, + ], }; export default data; diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/POSBlockRow.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/POSBlockRow.doc.ts index 13af8878a5..17ead607c9 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/POSBlockRow.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/POSBlockRow.doc.ts @@ -6,26 +6,55 @@ const generateCodeBlockForPOSBlockRow = (title: string, fileName: string) => const data: ReferenceEntityTemplateSchema = { name: 'POSBlockRow', - description: 'Renders a `POSBlockRow` in a `POSBlock`.', + description: + "The `POSBlockRow` component renders individual rows within a `POSBlock` container. Use it to create structured content rows with optional tap interactions inside `POSBlock` components.\n\nThe component follows Shopify's design system specifications to ensure visual consistency across the POS interface. It includes built-in support for different device sizes and orientations, providing a reliable and familiar experience for merchants across various retail environments and use cases.\n\n`POSBlockRow` components handle edge cases and loading states gracefully, providing clear feedback during operations and maintaining interface responsiveness even when processing intensive tasks or handling large datasets.", isVisualComponent: true, type: 'component', thumbnail: 'pos-block-row-thumbnail.png', definitions: [ { - title: 'POSBlockRow', - description: '', + title: 'Properties', + description: + 'Configure the following properties on the `POSBlockRow` component.', type: 'POSBlockRowProps', }, ], - category: 'Components', + category: 'UI components', + subCategory: 'Layout and structure', related: [], defaultExample: { image: 'pos-block-row-default.png', codeblock: generateCodeBlockForPOSBlockRow( - 'Render a POSBlockRow in a POSBlock', + 'Create structured rows within a block', 'default.example', ), + description: + 'Display individual rows within a POSBlock container with optional tap interactions. This example demonstrates creating structured content rows that follow POS design specifications, ensuring visual consistency and proper handling of various device sizes and orientations.', }, + subSections: [ + { + type: 'Generic', + anchorLink: 'best-practices', + title: 'Best practices', + sectionContent: ` +- **Organize content logically within rows:** Structure your \`POSBlockRow\` content to be scannable and focused. Each row should represent a discrete piece of information or functionality that users can easily understand and interact with. +- **Provide visual feedback for interactive rows:** When rows are interactive (have \`onPress\` callbacks), ensure users understand they can be tapped. +- **Keep row content concise and focused:** Design row content to be easily readable and actionable within the constrained space of a \`POSBlock\`. Focus on the most important information and avoid cluttering rows with excessive detail. +- **Maintain consistent interaction patterns:** Use similar \`onPress\` behaviors across different \`POSBlockRow\` instances in your extension to create predictable user experiences. Consistent interaction patterns help merchants understand and trust your extension. + `, + }, + { + type: 'Generic', + anchorLink: 'limitations', + title: 'Limitations', + sectionContent: ` +- \`POSBlockRow\` can only be used as children of \`POSBlock\` components—it can't be used independently or within other container types. +- The component's visual styling and layout are controlled by the POS design system—custom row styling beyond content organization isn't supported. +- Row content is provided through child components rather than direct content properties—organize your row content through component composition. +- Interactive behavior is limited to the \`onPress\` callback—complex interactions or multiple actions for each row require custom implementation within the row content. + `, + }, + ], }; export default data; diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/PinPad.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/PinPad.doc.ts index 539fcba75b..def465b2d2 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/PinPad.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/PinPad.doc.ts @@ -3,23 +3,25 @@ import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs'; const data: ReferenceEntityTemplateSchema = { name: 'PinPad', description: - 'A component used to authenticate or identify individuals through a standarized number pad.', + 'The `PinPad` component provides a secure numeric keypad interface for PIN entry and validation. Use it to collect PIN codes, passcodes, or other sensitive numeric input with proper masking and validation.\n\nThe component provides a secure numeric input interface specifically designed for PIN entry, with visual feedback that masks entered digits for security. It includes built-in validation for PIN length requirements, supports error states for invalid PINs, and provides haptic feedback on touch-enabled devices to confirm key presses during secure authentication workflows.\n\n`PinPad` components meets security standards for PIN entry by preventing screenshot capture and display recording, protecting sensitive authentication data during payment authorization and staff access workflows.', isVisualComponent: true, type: 'component', definitions: [ { - title: 'PinPad', - description: '', + title: 'Properties', + description: + 'Configure the following properties on the `PinPad` component.', type: 'PinPadProps', }, ], - category: 'Components', + category: 'UI components', + subCategory: 'Forms', related: [], thumbnail: 'pin-pad-thumbnail.png', defaultExample: { image: 'pin-pad-default.png', codeblock: { - title: 'Validation', + title: 'Validate a PIN securely', tabs: [ { code: '../examples/pinpad/validation.ts', @@ -27,65 +29,30 @@ const data: ReferenceEntityTemplateSchema = { }, ], }, + description: + 'Collect and validate PINs securely using a numeric keypad interface. This example demonstrates a PinPad with an `onPinSubmit` callback that validates entered PINs asynchronously. The validation function receives an array of numbers representing the entered digits and returns a Promise that resolves to `PinValidationResult` (either `"accept"` or `"reject"`). In this example, the validation simulates a 1-second async check against a test PIN sequence [1, 2, 3, 4, 5, 6]. The component masks digits for security, provides haptic feedback, and supports error states for invalid PINs—ideal for payment authorization or staff access workflows.', }, subSections: [ { type: 'Generic', - anchorLink: 'example', - title: 'Validating a PIN Example', + anchorLink: 'best-practices', + title: 'Best practices', sectionContent: ` -This code defines a function onPinSubmit that simulates the validation of a Personal Identification Number (PIN). The function takes an array of numbers as input, representing the PIN entered by a user. - -The function returns a Promise that resolves with a PinValidationResult, which can be either 'accept' or 'reject'. The Promise simulates an asynchronous operation using setTimeout with a delay of 1 second. - -This code simulates an asynchronous operation using the setTimeout callback. The code checks if the entered PIN matches the sequence [1, 2, 3, 4, 5, 6]. If the entered PIN matches this sequence, the Promise resolves with 'accept'; otherwise, it resolves with 'reject'. - -This function can be used to simulate PIN validation in a system where the correct PIN is [1, 2, 3, 4, 5, 6]. -`, - }, - { - type: 'Generic', - anchorLink: 'guidelines', - title: 'Guidelines', - sectionContent: ` -* Due to the nature of this component and the intended UX for this type of action, we recommend surfacing this in a full screen modal. - -* Please be advised that when utilizing the onSubmit callback, it is your responsibility to manage the navigation to the subsequent screen or dismissal of the modal. The component will only handle rejection of invalid PIN cases. +- **Mask sensitive entry:** Set \`masked\` to true for security-related PIN entry to prevent shoulder-surfing. +- **Set appropriate constraints:** Define \`minPinLength\` and \`maxPinLength\` based on security needs (4-6 for basic, 6-10 for higher security). +- **Validate securely on backend:** Use \`onSubmit\` for server-side verification. Return \`accept\` or \`reject\`. Implement rate limiting. +- **Write clear labels:** Use direct prompts like "Enter Manager PIN" rather than verbose text. +- **Use PIN terminology:** Always use "PIN" in all capitals. `, }, { type: 'Generic', - anchorLink: 'content-guidelines', - title: 'Content guidelines', + anchorLink: 'limitations', + title: 'Limitations', sectionContent: ` -When referring to a personal identification number, refer to it as a PIN, with all capital letters. - -Also when writing the PIN title or PinPadAction label: - -* Be concise -* Never go over 4 words -* Do not use punctuation -* Start with a capital letter - -### Title (Enter PIN) - -✅ [PIN pad title] Enter PIN
-✅ [PIN pad title] Enter staff PIN
-✅ [PIN pad title] Create PIN
-❌ [PIN pad title] Please put in a PIN
-❌ [PIN pad title] Create a PIN - -### PinPadAction (Generate random PIN, Clear) - -For PIN Pad actions, the action label should clearly communicate the action. - -✅ [PIN pad action label] Generate random PIN
-❌ [PIN pad action label] Please create a new random PIN - -You can use just [verb], if it's obvious from the surrounding context what the [item] is: - -✅ [PIN pad action label] Clear
-❌ [PIN pad action label] Clear PIN +- \`PinPad\` is designed for numeric PIN entry only—alphanumeric passcodes or complex passwords require different input components. +- PIN length is constrained to 4-10 digits—requirements outside this range need alternative authentication methods. +- The component provides the keypad interface and basic validation—additional security measures like rate limiting, attempt tracking, or lockout mechanisms must be implemented in your \`onSubmit\` callback. `, }, ], diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/RadioButtonList.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/RadioButtonList.doc.ts index bcedafef07..2104f4ec14 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/RadioButtonList.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/RadioButtonList.doc.ts @@ -4,27 +4,54 @@ import {generateCodeBlock} from '../helpers/generateCodeBlock'; const data: ReferenceEntityTemplateSchema = { name: 'RadioButtonList', description: - 'A radio button list lets merchants select from a given set of options.', + 'The `RadioButtonList` component presents radio button options for single selection from a list of string values. Use it when merchants need to choose exactly one option from a defined set of choices.\n\nThe component ensures single-selection behavior with clear visual indication of the selected option and disabled states for unavailable choices, making it suitable for settings, preferences, and any scenario requiring exclusive choice from multiple options.', isVisualComponent: true, type: 'component', definitions: [ { - title: 'RadioButtonList', - description: '', + title: 'Properties', + description: + 'Configure the following properties on the `RadioButtonList` component.', type: 'RadioButtonListProps', }, ], - category: 'Components', + category: 'UI components', + subCategory: 'Forms', related: [], thumbnail: 'radio-button-list-thumbnail.png', defaultExample: { image: 'radio-button-list-default.png', codeblock: generateCodeBlock( - 'RadioButtonList', + 'Select one option from a list', 'radio-button-list', 'default.example', ), + description: + 'Enable single selection from multiple options using radio buttons. This example demonstrates a RadioButtonList that presents exclusive choices with clear visual indication of the selected option, ideal for settings, preferences, or any scenario requiring one choice from several options.', }, + subSections: [ + { + type: 'Generic', + anchorLink: 'best-practices', + title: 'Best practices', + sectionContent: ` +- **Manage selection state in your app:** Use \`initialSelectedItem\` and \`onItemSelected\` together to manage selection state. When a user selects an item, \`onItemSelected\` fires with the selected value—you must then update \`initialSelectedItem\` with this new value to reflect the selection in the UI. +- **Enable auto-scrolling for better UX:** Set \`initialOffsetToShowSelectedItem\` to true when you have long lists and want. This improves usability by eliminating the need for users to scroll to find their current selection. +- **Track selections in your app code:** Maintain the selected item value in your app state (for example, using React [\`useState\`](https://react.dev/reference/react/useState)). When \`onItemSelected\` fires, update your state with the new selection, which will then update the \`initialSelectedItem\` property to reflect the change. +- **Consider list length and scrolling:** For long option lists, use the \`initialOffsetToShowSelectedItem\` property to improve initial display. Design your interface to handle scrollable lists gracefully, especially on smaller POS device screens. + `, + }, + { + type: 'Generic', + anchorLink: 'limitations', + title: 'Limitations', + sectionContent: ` +- \`RadioButtonList\` accepts only string arrays for options—complex option objects with additional metadata or custom rendering require alternative components or additional state management. +- The component is designed for single selection only—multiple selection scenarios require alternative approaches or custom implementation. +- \`RadioButtonList\` requires you to manage the selected value in your app must update \`initialSelectedItem\` in response to \`onItemSelected\` events to reflect the new selection in the UI. + `, + }, + ], }; export default data; diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/Screen.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/Screen.doc.ts index a678e7f4d7..9256f830b4 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/Screen.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/Screen.doc.ts @@ -7,13 +7,14 @@ const generateCodeBlockForComponent = (title: string, fileName: string) => const data: ReferenceEntityTemplateSchema = { name: 'Screen', description: - 'A component used in the root of a modal extension to define a screen.', + 'The `Screen` component represents a screen in the navigation stack with full control over presentation, actions, and navigation lifecycle. Use it to create navigable screens with titles, loading states, and custom navigation behavior.\n\nThe component manages full-screen presentations with proper navigation stack integration, allowing extensions to push and pop screens as part of the POS navigation flow. It handles transitions, back button behavior, and safe area padding automatically, ensuring extensions provide native-feeling navigation experiences on both iOS and Android devices.\n\n`Screen` components maintain scroll position across navigation operations where appropriate, allowing merchants to return to their previous location after viewing details or completing sub-tasks.', isVisualComponent: true, type: 'component', definitions: [ { - title: 'Screen', - description: '', + title: 'Properties', + description: + 'Configure the following properties on the `Screen` component.', type: 'ScreenProps', }, { @@ -27,34 +28,66 @@ const data: ReferenceEntityTemplateSchema = { type: 'SecondaryActionProps', }, ], - category: 'Components', + category: 'UI components', + subCategory: 'Layout and structure', related: [], thumbnail: 'screen-thumbnail.png', defaultExample: { image: 'screen-default.png', codeblock: generateCodeBlockForComponent( - 'Navigate to another screen', + 'Create a navigable screen', 'navigate', ), + description: + 'Define screens within your navigation stack with full control over presentation and behavior. This example shows how to create Screen components with titles, actions, and proper navigation integration, handling transitions and back button behavior automatically.', }, examples: { description: - 'Navigating using NavigationAPI with Screens within Navigators', + 'Learn how to create screens with navigation, pass data between screens, and use different presentation styles.', examples: [ { codeblock: generateCodeBlockForComponent( - 'Navigate to another screen with parameters', + 'Pass data between screens', 'navigate-params', ), + description: + 'Navigate to screens while passing data as parameters. This example demonstrates how to send information from one screen to another using navigation parameters, enabling contextual data flow through multi-step workflows.', }, { codeblock: generateCodeBlockForComponent( - 'Navigate to another screen with sheet presentation', + 'Present a screen as a sheet', 'navigate-sheet', ), + description: + 'Show a screen using sheet presentation style for modal-like interactions. This example demonstrates how to present screens as overlays that slide up from the bottom, useful for quick actions or secondary information without losing the parent screen context.', }, ], }, + subSections: [ + { + type: 'Generic', + anchorLink: 'best-practices', + title: 'Best practices', + sectionContent: ` +- **Implement proper loading states:** Use the \`isLoading\` property to provide visual feedback during async operations. Set it to \`true\` when starting data fetching or processing, and \`false\` when operations complete to maintain user awareness. +- **Handle navigation lifecycle appropriately:** Use \`onNavigate\` for screen initialization, \`onNavigateBack\` for cleanup operations, and \`onReceiveParams\` for handling passed data. Proper lifecycle management ensures smooth transitions and data consistency. +- **Choose appropriate presentation styles:** Use sheet presentation for focused tasks, modal-style interactions, or when you want to maintain context with the previous screen. Reserve standard presentation for primary navigation flows. +- **Design meaningful secondary actions:** When adding secondary actions, use clear, action-oriented text and ensure the action is relevant to the current screen's content. Disable actions when they're not applicable using the \`isEnabled\` property. +- **Override back navigation judiciously:** Use \`overrideNavigateBack\` only when you need to prevent data loss or handle unsaved changes. Most screens should use the default back navigation behavior to maintain consistent user expectations. + `, + }, + { + type: 'Generic', + anchorLink: 'limitations', + title: 'Limitations', + sectionContent: ` +- Screen components are designed for navigation stack contexts—they can't be used as general layout containers outside of navigation workflows. +- Only one secondary action is supported for each screen to maintain clean header layouts that don't overwhelm the interface. +- Screen presentation and styling are controlled by the POS navigation system—custom screen transitions or styling beyond the provided options aren't supported. +- Navigation parameter handling is limited to the \`onReceiveParams\` callback—complex parameter validation or transformation requires custom implementation within the callback. + `, + }, + ], }; export default data; diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/ScrollView.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/ScrollView.doc.ts index e6a4f203e6..3ac9cc25a4 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/ScrollView.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/ScrollView.doc.ts @@ -7,17 +7,46 @@ const generateCodeBlockForComponent = (title: string, fileName: string) => const data: ReferenceEntityTemplateSchema = { name: 'ScrollView', description: - 'The ScrollView component allows content that doesn’t fully fit on screen to scroll. Typically, the ScrollView component serves as the root component of a Screen.', + "The `ScrollView` component creates a scrollable container for content that exceeds the available display area. Use it to enable scrolling behavior for long content lists or detailed information that doesn't fit within screen constraints.\n\nThe component creates scrollable containers that automatically adjust to content size with optimized rendering for long lists and large content areas. It supports pull-to-refresh gestures, scroll position tracking, and lazy loading integration, providing smooth scrolling performance even with extensive content on resource-constrained POS hardware.\n\n`ScrollView` components provide scroll position tracking through callbacks, enabling features like back-to-top buttons, infinite scroll, and scroll-based animations that enhance the browsing experience.", isVisualComponent: true, type: 'component', definitions: [], - category: 'Components', + category: 'UI components', + subCategory: 'Layout and structure', related: [], thumbnail: 'scroll-view-thumbnail.png', defaultExample: { image: 'scroll-view-default.png', - codeblock: generateCodeBlockForComponent('ScrollView', 'default.example'), + codeblock: generateCodeBlockForComponent( + 'Create a scrollable container', + 'default.example', + ), + description: + 'Enable scrolling for content that exceeds available screen space. This example demonstrates a ScrollView that automatically adjusts to content size with optimized rendering, supporting pull-to-refresh and lazy loading for smooth performance with extensive content on POS hardware.', }, + subSections: [ + { + type: 'Generic', + anchorLink: 'best-practices', + title: 'Best practices', + sectionContent: ` +- **Organize content for efficient scrolling:** Structure your scrollable content logically with clear visual hierarchy, consistent spacing, and logical grouping. This helps users navigate efficiently through longer content areas. +- **Consider touch interface optimization:** \`ScrollView\` is optimized for touch-based POS devices, providing smooth scrolling with appropriate momentum and bounce effects. Design your content layout to take advantage of these touch-optimized behaviors. +- **Combine with other layout components strategically:** Use \`ScrollView\` in combination with other layout components like \`Stack\` or \`Section\` to create well-organized scrollable content areas. \`ScrollView\` handles the scrolling behavior while other components manage content arrangement. +- **Design for various content types:** \`ScrollView\` supports any valid POS UI extension components as children, allowing for flexible content organization. Use this flexibility to create rich, interactive scrollable experiences. + `, + }, + { + type: 'Generic', + anchorLink: 'limitations', + title: 'Limitations', + sectionContent: ` +- \`ScrollView\` automatically manage scroll behavior—manual scroll control or custom scroll physics are not available. +- Scroll styling and behavior are controlled by the POS design system—custom scroll bar appearance or scroll interactions beyond the default behavior aren't supported. +- The component provides basic scrolling functionality without advanced features like pull-to-refresh, infinite scrolling, or scroll position management that would require custom implementation. + `, + }, + ], }; export default data; diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/SearchBar.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/SearchBar.doc.ts index e34675d77a..eea309aa14 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/SearchBar.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/SearchBar.doc.ts @@ -5,55 +5,53 @@ import {generateCodeBlock} from '../helpers/generateCodeBlock'; const data: ReferenceEntityTemplateSchema = { name: 'SearchBar', description: - 'The search bar lets merchants enter search queries for objects throughout the app.', + 'The `SearchBar` component provides a specialized input field for search functionality with built-in search button and text change handling. Use it to enable product searches, customer lookups, or other search-driven workflows in POS interfaces.\n\nThe component includes a dedicated search input with built-in search icon, clear button, and cancel functionality following platform-specific search patterns. It provides visual feedback for search states, supports voice input where available, and integrates with platform search behaviors to deliver familiar search experiences on both iOS and Android POS devices.\n\n`SearchBar` components maintain search focus during typing and automatically dismisses the keyboard when search is submitted, streamlining the search workflow and reducing unnecessary interaction steps.', isVisualComponent: true, type: 'component', definitions: [ { - title: 'SearchBar', - description: '', + title: 'Properties', + description: + 'Configure the following properties on the `SearchBar` component.', type: 'SearchBarProps', }, ], - category: 'Components', - related: [ - { - name: 'ProductSearch API', - subtitle: - 'See how to use the ProductSearch API with a SearchBar to search for products.', - url: '/api/pos-ui-extensions/apis/productsearch-api#example-search-for-products-with-a-search-bar', - }, - ], + category: 'UI components', + subCategory: 'Navigation and content', + related: [], thumbnail: 'search-bar-thumbnail.png', defaultExample: { image: 'search-bar-default.png', - codeblock: generateCodeBlock('SearchBar', 'search-bar', 'default.example'), + codeblock: generateCodeBlock( + 'Add search functionality', + 'search-bar', + 'default.example', + ), + description: + 'Implement search functionality with a specialized input field. This example shows a SearchBar with built-in search icon, clear button, and text change handling, enabling product searches, customer lookups, or other search-driven workflows following platform-specific patterns.', }, subSections: [ { type: 'Generic', - anchorLink: 'guidelines', - title: 'Guidelines', + anchorLink: 'best-practices', + title: 'Best practices', sectionContent: ` -- The global search bar should appear at the very top of a view, above the header. This is because it searches for things beyond the scope of that page. -- The inline search bar should appear at the top of a list, but under the header. -- The search bar should be sticky and remain at the top of the page when the merchant scrolls. -- When a merchant selects the search bar, the bar enters the focused state. -- When entering the focused state, the border turns blue and the search icon changes to a back arrow icon. Selecting the back arrow lets merchants return to the default state. -- If it's an inline search bar, entering focused state should also move the search bar to the top of the screen. -- When a merchant starts entering a search query, the bar enters the filled state. -- Selecting the **X** deletes the merchant's search query, but keeps them in the focused state so that they can immediately enter a new search query. +- **Implement sticky behavior for persistent access:** Make search bars sticky so they remain at the top of the page when merchants scroll. +- **Handle focus states with proper visual feedback:** When merchants select the search bar, ensure it enters the focused state with a blue border and the search icon changes to a back arrow. +- **Optimize inline search bar positioning:** For inline search bars, entering the focused state should move the search bar to the top of the screen for better visibility and easier interaction, especially when the on-screen keyboard appears. +- **Manage search query states effectively:** When merchants start entering text, transition the search bar to the filled state. Implement clear functionality (X button) that deletes the search query but keeps the search bar in focused state, allowing immediate entry of new search terms. +- **Write effective placeholder text:** Use the pattern "Search \`{items}\`" for placeholder text (for example, "Search staff" not just "Search"). This clearly communicates what type of content can be searched and sets proper user expectations. +- **Implement responsive search patterns:** Use \`onTextChange\` for real-time search experiences like autocomplete or instant filtering, and \`onSearch\` for explicit search actions. Consider implementing debouncing for text change events to avoid excessive API calls during typing. `, }, { type: 'Generic', - anchorLink: 'content-guidelines', - title: 'Content guidelines', + anchorLink: 'limitations', + title: 'Limitations', sectionContent: ` -For the placeholder text, use the pattern: "Search {items}" - -✅ Search staff -❌ Search +- \`SearchBar\` provides the input interface but requires integration with the Product Search API or custom search logic for actual search functionality. +- The component handles basic text input and search button interactions—advanced search features like filters, sorting controls, or search history require additional components or custom implementation. +- Search result display and management are not included in the \`SearchBar\` component—use other components like List or custom layouts to present search results to users. `, }, ], diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/Section.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/Section.doc.ts index 4ca99d8bd5..777ae9785c 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/Section.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/Section.doc.ts @@ -6,15 +6,15 @@ const generateCodeBlockForComponent = (title: string, fileName: string) => const data: ReferenceEntityTemplateSchema = { name: 'Section', - description: `A component used to group other components together in a card-like UI. Usually, sections will be used inside a ScrollView. - > Note: - > Section no longer has a border as of POS 10.0.0.`, + description: + 'The `Section` component groups related content into clearly-defined thematic areas. Sections provide visual boundaries and optional actions to organize content within POS interfaces.\n\nUse sections to create structured layouts with clear titles and actionable elements that help users navigate and interact with grouped content.\n\nThe component supports customizable section dividers and spacing between sections, allowing you to create visual rhythm and hierarchy that guides merchants through complex forms and settings interfaces. Sections can be nested to create hierarchical content organization, with each level automatically adjusting its visual styling and semantic meaning to maintain clear structure and relationships throughout complex interfaces.\n\nThe `Section` component no longer has a border as of POS version 10.0.0.', isVisualComponent: true, type: 'component', definitions: [ { - title: 'Section', - description: '', + title: 'Properties', + description: + 'Configure the following properties on the `Section` component.', type: 'SectionProps', }, { @@ -23,13 +23,43 @@ const data: ReferenceEntityTemplateSchema = { type: 'SectionHeaderAction', }, ], - category: 'Components', + category: 'UI components', + subCategory: 'Layout and structure', related: [], thumbnail: 'section-thumbnail.png', defaultExample: { image: 'section-default.png', - codeblock: generateCodeBlockForComponent('Section', 'default.example'), + codeblock: generateCodeBlockForComponent( + 'Group related content', + 'default.example', + ), + description: + 'Organize content into clearly-defined thematic areas using sections. This example demonstrates grouping related content with titles and optional actions, creating visual boundaries and structured layouts that help merchants navigate complex interfaces.', }, + subSections: [ + { + type: 'Generic', + anchorLink: 'best-practices', + title: 'Best practices', + sectionContent: ` +- **Design meaningful action buttons:** When providing an action, use clear and descriptive button titles that indicate exactly what will happen when pressed. Avoid generic terms like "Action" in favor of specific actions like "Edit Settings" or "Add Item." +- **Group related content logically:** Use sections to group content that belongs together conceptually. Each section should contain related information or controls that users would expect to find together, creating intuitive content organization. +- **Implement responsive action callbacks:** Consider showing loading states or confirmation messages when actions require network requests or significant processing time. +- **Maintain consistent section patterns:** Establish consistent patterns for how you use sections across your POS UI extension. Similar types of content should be structured similarly, helping users develop familiarity with your interface organization. +- **Consider visual hierarchy and spacing:** Use sections strategically to create clear visual hierarchy in your interface. + `, + }, + { + type: 'Generic', + anchorLink: 'limitations', + title: 'Limitations', + sectionContent: ` +- Section content is determined by child components rather than direct content properties—organize your content structure through component composition. +- Only one action button is supported per section to maintain clean, focused interfaces that integrate well with existing POS workflows. +- The component's visual styling and layout are controlled by the POS design system—custom section styling beyond the provided properties is not supported. + `, + }, + ], }; export default data; diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/SectionHeader.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/SectionHeader.doc.ts index 860c0abe00..fb47ef7327 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/SectionHeader.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/SectionHeader.doc.ts @@ -4,27 +4,53 @@ import {generateCodeBlock} from '../helpers/generateCodeBlock'; const data: ReferenceEntityTemplateSchema = { name: 'SectionHeader', description: - 'A heading style text component with an optional divider line to structure content.', + 'The `SectionHeader` component displays a title with an optional action button and divider line. Use it to create consistent section headings with interactive elements that organize content and provide contextual actions.\n\nThe component provides a consistent header layout for section groupings with support for titles, actions, and dividers following POS design specifications. It ensures proper visual hierarchy and spacing within forms and settings interfaces, helping merchants understand content organization and providing quick access to section-level actions.\n\n`SectionHeader` components ensure consistent header styling and spacing across all sections while allowing action button customization, maintaining visual unity while supporting context-specific functionality.', isVisualComponent: true, type: 'component', definitions: [ { - title: 'SectionHeader', - description: '', + title: 'Properties', + description: + 'Configure the following properties on the `SectionHeader` component.', type: 'SectionHeaderProps', }, ], - category: 'Components', + category: 'UI components', + subCategory: 'Layout and structure', related: [], thumbnail: 'section-header-thumbnail.png', defaultExample: { image: 'section-header-default.png', codeblock: generateCodeBlock( - 'SectionHeader', + 'Add a section header with actions', 'section-header', 'default.example', ), + description: + 'Create consistent section headings with titles, optional action buttons, and divider lines. This example shows a SectionHeader that organizes content with proper visual hierarchy, helping merchants understand content structure and providing quick access to section-level actions.', }, + subSections: [ + { + type: 'Generic', + anchorLink: 'best-practices', + title: 'Best practices', + sectionContent: ` +- **Design meaningful action buttons:** When providing an action, use clear and descriptive button labels that indicate exactly what will happen when pressed. Avoid generic terms like "Action" in favor of specific actions like "Edit Settings" or "Add Item." +- **Control divider visibility strategically:** Use the \`hideDivider\` property to control visual separation based on your layout needs. Show dividers when you need clear section boundaries, and hide them when the visual separation might create unnecessary visual clutter. + `, + }, + { + type: 'Generic', + anchorLink: 'limitations', + title: 'Limitations', + sectionContent: ` +- Action buttons require a title to function properly—\`SectionHeader\` can't display actions without an accompanying title. +- Only one action button is supported per \`SectionHeader\` to maintain clean, focused interfaces that don't overwhelm users. +- The component's visual styling and layout are controlled by the POS design system—custom header styling beyond the provided properties is not supported. +- \`SectionHeader\` is a standalone component separate from \`Section\`—it doesn't automatically integrate with \`Section\` component functionality or provide the same semantic benefits. + `, + }, + ], }; export default data; diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/SegmentedControl.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/SegmentedControl.doc.ts index 694aabefbd..edb1cf2994 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/SegmentedControl.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/SegmentedControl.doc.ts @@ -5,27 +5,55 @@ import {generateCodeBlock} from '../helpers/generateCodeBlock'; const data: ReferenceEntityTemplateSchema = { name: 'SegmentedControl', description: - 'The segmented control lets the merchant easily switch between different lists or views on the same page.', + 'The `SegmentedControl` component displays a horizontal row of segments that allow users to switch between different views or filter content. Use it to provide mutually exclusive options with clear visual selection states.\n\nThe component provides mutually exclusive selection within a compact horizontal layout, with visual highlighting of the active segment and smooth transition animations, making it ideal for view switching, filter controls, or any interface requiring clear, space-efficient option selection.\n\n`SegmentedControl` components provide animated transitions between segments that clearly indicate state changes without being distracting, helping merchants confirm their selection while maintaining focus on content.', isVisualComponent: true, type: 'component', definitions: [ { - title: 'SegmentedControl', - description: '', + title: 'Properties', + description: + 'Configure the following properties on the `SegmentedControl` component.', type: 'SegmentedControlProps', }, ], - category: 'Components', + category: 'UI components', + subCategory: 'Navigation and content', related: [], thumbnail: 'segmented-control-thumbnail.png', defaultExample: { image: 'segmented-control-default.png', codeblock: generateCodeBlock( - 'SegmentedControl', + 'Switch between views or filters', 'segmented-control', 'default.example', ), + description: + 'Enable view switching or content filtering with mutually exclusive segments. This example shows a SegmentedControl that displays options in a compact horizontal layout with clear visual selection states and smooth transitions, ideal for view toggles or filter controls.', }, + subSections: [ + { + type: 'Generic', + anchorLink: 'best-practices', + title: 'Best practices', + sectionContent: ` +- **Limit the number of segments appropriately:** Use two to five segments for optimal usability. Too few segments may not justify the component, while too many can overwhelm users and reduce touch target sizes on POS devices. +- **Implement meaningful selection logic:** Provide immediate visual feedback by updating content, filters, or views based on the selection. +- **Handle disabled states strategically:** Use the \`disabled\` property on individual segments when options are temporarily unavailable or contextually inappropriate. Provide clear visual indication and consider alternative messaging when segments are disabled. +- **Design for touch interfaces:** Ensure segments are large enough for comfortable touch interaction on POS devices. +- **Maintain consistent selection patterns:** Keep the same segment selected when users navigate away and return to a screen, unless the context has changed significantly. This helps maintain user orientation and reduces cognitive load. + `, + }, + { + type: 'Generic', + anchorLink: 'limitations', + title: 'Limitations', + sectionContent: ` +- \`SegmentedControl\` is designed for mutually exclusive selections—multiple selection scenarios require different components like checkbox lists or choice lists. +- The component provides the selection interface but doesn't manage content switching—you must implement the logic to show/hide or update content based on the selected segment. +- Visual styling and layout are controlled by the POS design system—custom segment styling or layout modifications beyond the provided properties are not supported. + `, + }, + ], }; export default data; diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/Selectable.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/Selectable.doc.ts index a23c4950cd..bb9614ecc3 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/Selectable.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/Selectable.doc.ts @@ -4,23 +4,54 @@ import {generateCodeBlock} from '../helpers/generateCodeBlock'; const data: ReferenceEntityTemplateSchema = { name: 'Selectable', description: - 'The selectable component allows you to wrap any non-interactive UI component to make it selectable.', + "The `Selectable` component allows you to wrap any non-interactive UI component to make it selectable. Use `Selectable` to add tap interactions to components that don't normally respond to user input while maintaining their original styling.\n\nWrap non-interactive components like `Text`, `Image`, `Icon`, or custom layouts that need tap functionality. Don't wrap components that already have built-in interactions like `Button` or `TextField`. `Selectable` components maintain consistent selection state across re-renders and navigation, ensuring merchants don't lose their choices when moving between screens or interacting with other interface elements.", isVisualComponent: true, type: 'component', definitions: [ { - title: 'Selectable', - description: '', + title: 'Properties', + description: + 'Configure the following properties on the `Selectable` component.', type: 'SelectableProps', }, ], - category: 'Components', + category: 'UI components', + subCategory: 'Actions', related: [], thumbnail: 'selectable-thumbnail.png', defaultExample: { image: 'selectable-default.png', - codeblock: generateCodeBlock('Selectable', 'selectable', 'default.example'), + codeblock: generateCodeBlock( + 'Make components tappable', + 'selectable', + 'default.example', + ), + description: + 'Add tap interactions to non-interactive components while preserving their appearance. This example demonstrates wrapping components like Text, Image, or Icon with Selectable to make them respond to user input without changing their original styling or layout.', }, + subSections: [ + { + type: 'Generic', + anchorLink: 'best-practices', + title: 'Best practices', + sectionContent: ` +- **Use meaningful press handlers:** Implement \`onPress\` callbacks that perform clear, expected actions. Users should understand what will happen when they tap the selectable content based on its visual presentation and context. +- **Disable when appropriate:** Use the \`disabled\` property to prevent interactions when the selectable content shouldn't respond to user input, such as during loading states or when certain conditions aren't met. +- **Maintain consistent interaction patterns:** Keep selectable interactions consistent with other interactive elements in your interface. Users should have predictable experiences when tapping different types of content. + `, + }, + { + type: 'Generic', + anchorLink: 'limitations', + title: 'Limitations', + sectionContent: ` +- Selectable components don't provide built-in visual feedback for interactions. You must implement selection indicators yourself. +- The component is designed for wrapping non-interactive content. Wrapping already-interactive components may cause unexpected behavior. +- Complex nested interactions within selectable content aren't supported and may interfere with the tap functionality. +- Selectable components don't support keyboard navigation or focus management beyond basic tap interactions. + `, + }, + ], }; export default data; diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/Spacing.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/Spacing.doc.ts index d0edf1217d..12365bb23e 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/Spacing.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/Spacing.doc.ts @@ -4,7 +4,7 @@ import {generateCodeBlock} from '../helpers/generateCodeBlock'; const data: ReferenceEntityTemplateSchema = { name: 'Spacing', description: - 'Set of spacing constants to be used in the UI Extensions components library.', + "The `Spacing` component provides a set of spacing constants to be used in the POS UI extensions components library. Use these predefined values to maintain consistent spacing and layout patterns across POS interfaces.\n\nThe component provides access to design system spacing tokens through a set of predefined constants, ensuring consistent spacing throughout extensions. It eliminates the need for hardcoded pixel values by offering semantic spacing values that automatically adapt to design system changes, maintaining visual consistency across different screen sizes and orientations.\n\n`Spacing` components provide semantic spacing names like 'tight', 'loose', and 'extraLoose' that map to specific design system values, making spacing choices more intuitive and maintainable.", isVisualComponent: true, type: 'component', definitions: [ @@ -19,13 +19,44 @@ const data: ReferenceEntityTemplateSchema = { type: 'HorizontalSpacing', }, ], - category: 'Components', + category: 'UI components', + subCategory: 'Layout and structure', related: [], thumbnail: 'spacing-thumbnail.png', defaultExample: { image: 'spacing-default.png', - codeblock: generateCodeBlock('Spacing', 'spacing', 'default.example'), + codeblock: generateCodeBlock( + 'Use consistent spacing values', + 'spacing', + 'default.example', + ), + description: + 'Apply consistent spacing patterns using design system tokens. This example demonstrates using predefined spacing constants instead of hardcoded pixel values, ensuring visual consistency that automatically adapts to design system changes across different screen sizes.', }, + subSections: [ + { + type: 'Generic', + anchorLink: 'best-practices', + title: 'Best practices', + sectionContent: ` +- **Apply numeric spacing for precise control:** Use the numeric spacing values when you need precise control over spacing amounts, particularly in \`Stack\` components where exact spacing relationships are important for visual hierarchy. +- **Maintain consistent spacing patterns:** Establish consistent patterns for how you use spacing values across your extension. Similar types of content should use similar spacing values, helping users develop familiarity with your interface organization. +- **Consider touch interface requirements:** Ensure adequate spacing for touch-based interactions by using appropriate spacing values that provide comfortable touch targets. POS interfaces require generous spacing for reliable touch interaction. +- **Balance spacing with content density:** Choose spacing values that balance content density with readability. Use smaller spacing values for information-dense interfaces and larger values when content needs breathing room. +- **Align spacing with visual hierarchy:** Use larger spacing values to separate major content areas and smaller values for related elements. This creates clear visual hierarchy that helps users understand content relationships. + `, + }, + { + type: 'Generic', + anchorLink: 'limitations', + title: 'Limitations', + sectionContent: ` +- Spacing values are predefined constants—custom spacing values outside the provided scales aren't supported to maintain design system consistency. +- The \`Spacing\` component is primarily designed for layout components like \`Stack\`—not all components support all spacing types. +- Spacing behavior may vary between different POS device screen sizes and resolutions, though the relative relationships between spacing values remain consistent. + `, + }, + ], }; export default data; diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/Stack.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/Stack.doc.ts index 5f12bc50ca..5f85ba8cf6 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/Stack.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/Stack.doc.ts @@ -16,141 +16,114 @@ const generateCodeBlockForStack = (title: string, fileName: string) => { const data: ReferenceEntityTemplateSchema = { name: 'Stack', description: - 'A container for other components that allows them to be stacked horizontally or vertically. When building complex UIs, this will be your primary building block.', + 'The `Stack` component organizes elements horizontally or vertically along the block or inline axis. Use it to structure layouts, group related components, or control spacing between elements with flexible alignment options.\n\nThe component simplifies layout creation by automatically managing spacing between child elements through gap properties, eliminating the need for manual margin management. It supports both horizontal and vertical arrangements, flexible alignment options, and wrapping behavior, making it the foundation for building consistent, responsive layouts throughout POS extensions.\n\n`Stack` components support responsive gap values that automatically adjust spacing based on screen size, ensuring layouts remain visually balanced and maintain proper element separation across different devices.', isVisualComponent: true, type: 'component', definitions: [ { - title: 'Stack', - description: '', + title: 'Properties', + description: + 'Configure the following properties on the `Stack` component.', type: 'StackProps', }, ], + category: 'UI components', + subCategory: 'Layout and structure', + related: [], + thumbnail: 'stack-thumbnail.png', + defaultExample: { + image: 'stack-default.png', + codeblock: generateCodeBlockForStack( + 'Layout elements horizontally or vertically', + 'horizontal-default', + ), + description: + 'Organize UI elements horizontally or vertically with automatic spacing management. This example shows a Stack with default values, demonstrating how to structure layouts and control element spacing through gap properties without manual margin management.', + }, + examples: { + description: + 'Learn how to create flexible layouts with inline and block stacks, control alignment, and nest stacks for complex UIs.', + examples: [ + { + codeblock: generateCodeBlockForStack( + 'Arrange elements vertically', + 'vertical', + ), + description: + 'Stack elements vertically by setting `direction="block"`. This creates a vertical layout with automatic gap spacing between elements, ideal for forms, lists, or any vertically-stacked content.', + image: 'extension-stack-vertical.png', + }, + { + codeblock: generateCodeBlockForStack( + 'Center content on both axes', + 'vertical-center-children', + ), + description: + 'Center elements both horizontally and vertically using `justifyContent="center"`, `alignContent="center"`, and `alignItems="center"` with custom `blockSize="50%"` and `inlineSize="100%"`. All three alignment properties work together to create perfectly centered content on both axes.', + image: 'extension-stack-vertical-center.png', + }, + { + codeblock: generateCodeBlockForStack( + 'Center elements horizontally', + 'horizontal-center-children', + ), + description: + 'Center elements horizontally using `justifyContent="center"` with `flexChildren={false}` (default). This positions children in the center while keeping them at their minimum required size, ideal for centered button groups without stretching.', + image: 'extension-stack-horizontal-centered.png', + }, + { + codeblock: generateCodeBlockForStack( + 'Expand children to fill available space', + 'horizontal-flex-children', + ), + description: + 'Make child components expand to fill available space in an inline stack using `flexChildren={true}`. This stretches the two buttons to occupy maximum space within the inline container, distributing space evenly across children for full-width layouts.', + image: 'extension-stack-horizontal-flexChildren.png', + }, + { + codeblock: generateCodeBlockForStack( + 'Create complex layouts with nested stacks', + 'nested', + ), + description: + 'Nest multiple stacks to build sophisticated layouts. This example creates a tappable row using an inline parent stack with `justifyContent="space-between"` and `inlineSize="100%"` containing two child stacks: a block stack (left) with gap 100 for labels, and an inline stack (right) with gap 600 for text and icon. The entire structure is wrapped in a Selectable component for tap interaction with visual highlight.', + image: 'extension-stack-nested.png', + }, + { + codeblock: generateCodeBlockForStack( + 'Space elements apart vertically', + 'vertical-bottom-children', + ), + description: + 'Distribute children vertically using `justifyContent="space-between"` with `blockSize="50%"` for custom height. This example removes the ScrollView wrapper and adds `inlinePadding="450"` to mimic screen header padding, spreading children across the available height with maximum spacing.', + image: 'extension-stack-vertical-flex-end.png', + }, + ], + }, subSections: [ { type: 'Generic', - anchorLink: 'examples', - title: 'Examples', - sectionContent: ` -The following examples will demonstrate some, but not all of the abilities of the \`Stack\` component. In all the following examples we will be applying \`horizontalPadding\` of \`ExtraExtraLarge\`, since this is the default that we use on POS when we wrap our screens. For simplicity, these examples use the React version of the \`Stack\` component, but the same results will be achieved by using the same props with the regular JS library. -`, - }, - { - type: 'Generic', - anchorLink: 'horizontal-default', - title: 'Horizontal Stack with default values', + anchorLink: 'best-practices', + title: 'Best practices', sectionContent: ` -In this example, we specify \`horizontal\` for the \`direction\`. We don't specify the \`flex\`, which means it's 0 by default. However, \`horizontal\` stacks will always stretch to fill from the left to the right of the screen. As you can see, we have two small buttons occupying just the amount of space that they need, at the left side of the \`Stack\`. This is because \`alignment\` is set to \`flex-end\` by default. -`, - codeblock: generateCodeBlockForStack( - 'Horizontal Stack with default values', - 'horizontal-default', - ), - image: 'extension-stack-horizontal.png', - }, - { - type: 'Generic', - anchorLink: 'horizontal-flex-children', - title: 'Horizontal Stack with flexChildren', - sectionContent: ` -Similar to the example above, but this time we are specifying \`flexChildren\` to be \`true\`. This means that the two buttons will take up the max amount of space that they can within the \`horizontal\` stack. +- **Apply consistent spacing using numeric values:** Use the predefined numeric spacing values (0.5 through 16) to maintain consistency across your interface. Start with 3 or 4 for standard spacing and adjust up or down based on your content hierarchy needs. +- **Use semantic padding for consistent layouts:** Apply \`paddingVertical\` and \`paddingHorizontal\` using the semantic spacing values (\`HalfPoint\` through \`ExtraLarge\`) to create consistent padding patterns that align with the POS design system. +- **Use alignment properties for professional layouts:** Use the \`alignment\` property to control cross-axis positioning. Choose \`'flex-start'\` for natural alignment, \`'center'\` for centered layouts, or distribution values like \`'space-between'\` for evenly distributed content. +- **Control flex behavior strategically:** Use the \`flex\` property to make \`Stack\` components grow or shrink within their containers, and \`flexChildren\` to stretch child elements to fill available cross-axis space when needed. +- **Manage wrapping behavior appropriately:** Use \`flexWrap\` to control how children behave when they exceed container space. Choose \`'wrap'\` for responsive layouts, \`'nowrap'\` for fixed layouts, or \`'wrap-reverse'\` for specialized arrangements. `, - codeblock: generateCodeBlockForStack( - 'Horizontal Stack with flexChildren', - 'horizontal-flex-children', - ), - image: 'extension-stack-horizontal-flexChildren.png', - }, - { - type: 'Generic', - anchorLink: 'horizontal-center-children', - title: 'Horizontal Stack with centered children', - sectionContent: ` -You can also center elements in your \`horizontal\` stack. For this, you can specify the \`alignment\` to be \`center\`. However, in this case you also want \`flexChildren\` to be \`false\` (which is the default), so that the children can take up the minimal amount of space that they need, and be centered. -`, - codeblock: generateCodeBlockForStack( - 'Horizontal Stack with centered children', - 'horizontal-center-children', - ), - image: 'extension-stack-horizontal-centered.png', - }, - { - type: 'Generic', - anchorLink: 'horizontal-end-children', - title: 'Horizontal Stack with children at the end', - sectionContent: ` -To make the children be aligned to the end of your \`horizontal\` container, you just need to specify \`alignment\` to be \`flex-end\`. Note that in the first example, the children were at the start of the container. This is because the default value is \`flex-start\`. -`, - codeblock: generateCodeBlockForStack( - 'Horizontal Stack with children at the end', - 'horizontal-end-children', - ), - image: 'extension-stack-horizontal-flex-end.png', }, { type: 'Generic', - anchorLink: 'vertical', - title: 'Vertical Stack', + anchorLink: 'limitations', + title: 'Limitations', sectionContent: ` -You can specify your \`Stack\` to layout its children vertically by setting \`direction\` to \`vertical\`. - `, - codeblock: generateCodeBlockForStack('Vertical Stack', 'vertical'), - image: 'extension-stack-vertical.png', - }, - { - type: 'Generic', - anchorLink: 'vertical-center-children', - title: 'Vertical Stack with centered children', - sectionContent: ` -You can center your stack's children along the \`vertical\` axis by setting the \`alignment\` to \`center\`. However, because \`vertical\` stacks only take up the minimal amount of \`vertical\` space required when \`flex\` is set to \`0\` (which is by default), you will need to set \`flex\` to \`1\` -`, - codeblock: generateCodeBlockForStack( - 'Vertical Stack with centered children', - 'vertical-center-children', - ), - image: 'extension-stack-vertical-center.png', - }, - { - type: 'Generic', - anchorLink: 'vertical-bottom-children', - title: 'Vertical Stack with children at the bottom', - sectionContent: ` -You can set your children to the bottom of your \`vertical\` stack by setting \`alignment\` to \`flex-end\`. As explained in the previous example, you also need to set \`flex\` to \`1\`, since the default is \`0\`, which will make your container only take up the minimum amount of space it needs. -`, - codeblock: generateCodeBlockForStack( - 'Vertical Stack with children at the bottom', - 'vertical-bottom-children', - ), - image: 'extension-stack-vertical-flex-end.png', - }, - { - type: 'Generic', - anchorLink: 'nested', - title: 'Nested Stack', - sectionContent: ` -Now that we've run through a few examples of what a \`Stack\` can do, let's move on to something more complex. You can nest multiple Stacks of different configurations to achieve a more complex UI. In this example, we will create a row that displays several labels and an icon. This will mimic some of the basic rows that you can find across different POS screens. - -Let's put the \`Selectable\` aside for now; we'll get to that later. If you look at the first \`Stack\`, this is our parent \`Stack\`. We've set its \`direction\` to \`horizontal\` and its \`alignment\` to \`space-between\`. Then, we've added some vertical and horizontal padding (as highlighted in the screenshot). - -As you can see, there are two child Stacks. Because the parent \`Stack\` is set to \`space-between\`, these two child Stacks are spread to each end of the parent horizontal \`Stack\`. Both of these child Stacks occupy the amount of space they need, but not more. - -The first child \`Stack\` is a simple vertical \`Stack\` that stacks the two left labels. It specifies the \`spacing\` to be \`0.5\` (the default is \`1\`, and this was a bit too much). - -The second child \`Stack\` has another nested \`Stack\`. Let's discuss the nested \`Stack\` first. This is a horizontal \`Stack\` that lays out a text label and an icon horizontally. We then apply a bit of padding. That horizontal \`Stack\` is wrapped in a vertical \`Stack\`. The reason for this is to align the horizontal \`Stack\` on the center of the vertical axis, giving it a nicer appearance. Without it, the horizontal \`Stack\` would be located at the same height as the "Hello world!" \`Text\` on the left side of our row. But by specifying a \`flex\` of \`1\`, we are telling the vertical \`Stack\` to take as much vertical space as it can within its parent container. And then we specify an alignment of center, which lays out its child horizontal \`Stack\` on the center of its vertical axis. - -Finally, we can return to the \`Selectable\`. You'll notice that we've wrapped the entire \`Stack\` in a \`Selectable\`. This makes the entire \`Stack\` within the \`Selectable\` become a tappable surface, with an \`onPress\` handler, which is part of the \`Selectable\` component. It also gives a nice highlight effect when you tap, as you can see in the screenshot. -`, - codeblock: generateCodeBlockForStack('Nested Stack', 'nested'), - image: 'extension-stack-nested.png', +- Direction is limited to vertical and horizontal orientations—diagonal or complex arrangements require multiple nested \`Stack\` components or alternative layout approaches. +- Spacing values are predefined numeric constants—custom spacing values outside the provided scale aren't supported to maintain design consistency. +- Flex behavior follows standard CSS flexbox rules—complex layout requirements may need multiple \`Stack\` components with different configurations for optimal results. + `, }, ], - category: 'Components', - related: [], - thumbnail: 'stack-thumbnail.png', - defaultExample: { - image: 'stack-default.png', - codeblock: generateCodeBlockForStack('Stack', 'horizontal-default'), - }, }; export default data; diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/Stepper.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/Stepper.doc.ts index 31c950b252..28d6a67eac 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/Stepper.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/Stepper.doc.ts @@ -3,23 +3,56 @@ import {generateCodeBlock} from '../helpers/generateCodeBlock'; const data: ReferenceEntityTemplateSchema = { name: 'Stepper', - description: 'A component used for increasing or decreasing quantities.', + description: + 'The `Stepper` component provides increment and decrement controls for numeric values with visual feedback. Use it to adjust quantities, counts, or other numeric values with clear visual buttons.\n\nThe component provides visual increment and decrement controls with customizable step values and min/max constraints to control numeric adjustments. It supports both button clicks and keyboard input for flexibility, with visual feedback for boundary conditions and disabled states to prevent invalid value entries during quantity adjustments or numeric configurations.\n\n`Stepper` components provide continuous increment behavior when buttons are held down, enabling rapid value changes while still supporting single-step precision adjustments for fine-tuned control.', isVisualComponent: true, type: 'component', definitions: [ { - title: 'Stepper', - description: '', + title: 'Properties', + description: + 'Configure the following properties on the `Stepper` component.', type: 'StepperProps', }, ], - category: 'Components', + category: 'UI components', + subCategory: 'Forms', related: [], thumbnail: 'stepper-thumbnail.png', defaultExample: { image: 'stepper-default.png', - codeblock: generateCodeBlock('Stepper', 'stepper', 'default.example'), + codeblock: generateCodeBlock( + 'Increment and decrement numeric values', + 'stepper', + 'default.example', + ), + description: + 'Adjust numeric values with visual increment and decrement controls. This example demonstrates a Stepper with customizable step values and min/max constraints, supporting both button clicks and keyboard input for quantity adjustments or numeric configurations.', }, + subSections: [ + { + type: 'Generic', + anchorLink: 'best-practices', + title: 'Best practices', + sectionContent: ` +- **Use initialValue for default starting points:** Set \`initialValue\` to a sensible default that makes sense for your use case, such as 1 for quantities or a typical value for settings. +- **Let the component manage its own state:** By default, \`Stepper\` manages its own internal state—you only need to respond to \`onValueChanged\` to capture the new value. Avoid using the \`value\` property unless you specifically need to override the internal state for external synchronization. +- **Handle value changes appropriately:** Implement the \`onValueChanged\` callback to capture value changes and update your application state, trigger calculations, or perform related actions based on the new numeric value. +- **Provide visual context for stepper values:** While \`Stepper\` handles the increment/decrement controls, consider displaying the current value prominently alongside the \`Stepper\` buttons so users can see the exact numeric value, not just the controls. +- **Design for touch interaction:** \`Stepper\` buttons are optimized for touch interaction on POS devices. Ensure adequate spacing around the \`Stepper\` buttons and consider the overall layout to prevent accidental taps on adjacent controls. + `, + }, + { + type: 'Generic', + anchorLink: 'limitations', + title: 'Limitations', + sectionContent: ` +- \`Stepper\` provides increment/decrement controls only—if users need to enter specific values directly by keyboard, combine \`Stepper\` with a \`NumberField\` component. +- The component manages integer values by default—fractional or decimal increments require using the optional \`value\` property with external state management. +- \`Stepper\` doesn't include labels or field descriptions—combine with \`Text\` components or other UI elements to provide context about what value is being adjusted. + `, + }, + ], }; export default data; diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/Text.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/Text.doc.ts index 3bbf90e9b2..ed876246d8 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/Text.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/Text.doc.ts @@ -4,13 +4,14 @@ import {generateCodeBlock} from '../helpers/generateCodeBlock'; const data: ReferenceEntityTemplateSchema = { name: 'Text', description: - 'Text can be rendered in different sizes and colors in order to structure content.', + 'The `Text` component displays text with specific visual styles and colors. Use it to present content with appropriate typography hierarchy and semantic coloring for different types of information.\n\nText provides a comprehensive typography system that ensures consistent styling and proper visual hierarchy across POS interfaces.\n\n`Text` components ensure proper text rendering across different device types and screen sizes while maintaining readability through appropriate line heights, letter spacing, and color contrast ratios. The component automatically adjusts line length for optimal readability based on container width, preventing overly long lines that reduce reading speed and comprehension in wider layouts.', isVisualComponent: true, type: 'component', definitions: [ { - title: 'Text', - description: '', + title: 'Properties', + description: + 'Configure the following properties on the `Text` component.', type: 'TextProps', }, { @@ -24,13 +25,43 @@ const data: ReferenceEntityTemplateSchema = { type: 'ColorType', }, ], - category: 'Components', + category: 'UI components', + subCategory: 'Layout and structure', related: [], thumbnail: 'text-thumbnail.png', defaultExample: { image: 'text-default.png', - codeblock: generateCodeBlock('Text', 'text', 'default.example'), + codeblock: generateCodeBlock( + 'Display text with visual hierarchy', + 'text', + 'default.example', + ), + description: + 'Show text with appropriate typography styles and semantic coloring. This example demonstrates different text variants and colors to create visual hierarchy, ensuring consistent styling and proper readability across different device types and screen sizes.', }, + subSections: [ + { + type: 'Generic', + anchorLink: 'best-practices', + title: 'Best practices', + sectionContent: ` +- **Apply semantic colors to convey meaning:** Use color to communicate the nature and intent of your content. Apply \`TextSuccess\` for positive outcomes, \`TextCritical\` for errors, \`TextWarning\` for cautions, and \`TextInteractive\` for clickable elements. +- **Maintain consistent typography patterns:** Establish consistent patterns for how you use text variants across your POS UI extension. Similar types of content should use similar variants, helping users develop familiarity with your interface hierarchy. +- **Use subdued colors strategically:** Apply \`TextSubdued\` for secondary information that supports but doesn't compete with primary content. Use \`TextDisabled\` only for truly inactive content that users can't interact with. +- **Balance emphasis with clarity:** Use highlighting and interactive colors sparingly to maintain their effectiveness. Too many emphasized elements can reduce the impact of truly important content. + `, + }, + { + type: 'Generic', + anchorLink: 'limitations', + title: 'Limitations', + sectionContent: ` +- Text content is provided through child components rather than direct text properties—organize your text content through component composition. +- Typography and color options are limited to the predefined design system variants—custom fonts, sizes, or colors beyond the available options aren't supported. +- Complex rich text formatting requires multiple \`Text\` components with different variants and colors rather than inline formatting options. + `, + }, + ], }; export default data; diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/TextArea.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/TextArea.doc.ts index 2e4a6119a7..4f337fb0aa 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/TextArea.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/TextArea.doc.ts @@ -4,23 +4,57 @@ import {generateCodeBlock} from '../helpers/generateCodeBlock'; const data: ReferenceEntityTemplateSchema = { name: 'TextArea', description: - 'Use a text input to allow merchants to input or modify multiline text.', + 'The `TextArea` component captures longer text content with a multi-line, resizable text input area. Use it to collect descriptions, notes, comments, or other extended text input in forms and data entry workflows.\n\nThe component provides a multi-line text input area that accommodates longer content. It supports validation and multi-line formatting, making it ideal for capturing detailed information such as order notes, product descriptions, or customer feedback that requires more than single-line input.', isVisualComponent: true, type: 'component', definitions: [ { - title: 'TextArea', - description: 'A text field which supports multiple lines.', + title: 'Properties', + description: + 'Configure the following properties on the `TextArea` component.', type: 'TextAreaProps', }, ], - category: 'Components', + category: 'UI components', + subCategory: 'Forms', related: [], thumbnail: 'text-area-thumbnail.png', defaultExample: { image: 'text-area-default.png', - codeblock: generateCodeBlock('Thumbnail', 'text-area', 'default.example'), + codeblock: generateCodeBlock( + 'Capture multi-line text input', + 'text-area', + 'default.example', + ), + description: + 'Collect longer text content using a multi-line resizable input area. This example shows a TextArea that supports validation and multi-line formatting, ideal for capturing descriptions, notes, comments, or extended information in forms and data entry workflows.', }, + subSections: [ + { + type: 'Generic', + anchorLink: 'best-practices', + title: 'Best practices', + sectionContent: ` +- **Provide helpful guidance with helpText and placeholder:** Use \`helpText\` for explain content expectations, formatting requirements, or character limits. Use placeholder text to provide examples of the expected content format or structure. +- **Implement character limits appropriately:** Set \`maxLength\` to prevent excessively long input that might cause display or processing issues. Provide feedback about character limits in the \`helpText\`, especially when users are approaching the limit. +- **Use clear and specific labels:** Provide descriptive labels that indicate what type of text content is expected, like specific examples rather than generic terms. +- **Handle validation for required fields:** The \`required\` property adds semantic meaning only. Implement validation logic in your onChange callback to check empty values and display errors. +- **Add action buttons for text operations:** Use the \`action\` property to provide helpful actions like "Clear," "Use Template," or "Format Text." This enhances usability by providing quick access to common text operations. +- **Differentiate between input and change callbacks:** Use \`onInput\` for immediate responses that need to happen as the user types, such as clearing validation errors or providing real-time feedback. Use \`onChange\` for updating the field's value and performing actions after editing completes (typically on blur). Don't use \`onInput\` to update the \`value\` property—this can cause performance issues and unexpected behavior. + `, + }, + { + type: 'Generic', + anchorLink: 'limitations', + title: 'Limitations', + sectionContent: ` +- \`TextArea\` has a maximum of 8 visible rows—content requiring more vertical space should use scrolling within the text area or alternative layouts with \`ScrollView\` components. +- The component provides multi-line text input but doesn't include rich text formatting capabilities—complex formatting like bold, italic, or lists requires alternative solutions or plain text representations. +- The \`required\` property adds semantic meaning only—it doesn't trigger automatic error display or validation, so you must implement validation logic manually. +- Action buttons are limited to simple press callbacks—complex action workflows require custom implementation or additional components. + `, + }, + ], }; export default data; diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/TextField.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/TextField.doc.ts index ab5a8e1ea9..1804ac1b8d 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/TextField.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/TextField.doc.ts @@ -4,47 +4,55 @@ import {generateCodeBlock} from '../helpers/generateCodeBlock'; const data: ReferenceEntityTemplateSchema = { name: 'TextField', description: - 'Use a text field to allow merchants to enter or edit text. If you want to specify the kind of input, then use a formatted text field.', + 'The `TextField` component captures single-line text input. Use it to collect short, free-form information in forms and data entry workflows.\n\nThe component supports various input configurations including placeholders, character limits, and validation. It includes built-in support for labels, helper text, and error states to guide merchants through data entry, ensuring accurate and efficient information capture across different retail scenarios.', isVisualComponent: true, type: 'component', definitions: [ { - title: 'TextField', + title: 'Properties', description: - 'Use a text field to allow merchants to input or modify multiline text.', + 'Configure the following properties on the `TextField` component.', type: 'NewTextFieldProps', }, ], - category: 'Components', + category: 'UI components', + subCategory: 'Forms', related: [], thumbnail: 'text-field-thumbnail.png', defaultExample: { image: 'text-field-default.png', - codeblock: generateCodeBlock('Name Input', 'text-field', 'name'), + codeblock: generateCodeBlock( + 'Capture single-line text input', + 'text-field', + 'name', + ), + description: + 'Collect short, free-form text using a single-line input field. This example shows a TextField with labels, placeholders, and validation support, ensuring accurate and efficient information capture for forms and data entry workflows.', }, subSections: [ { type: 'Generic', - anchorLink: 'guidelines', - title: 'Guidelines', + anchorLink: 'best-practices', + title: 'Best practices', sectionContent: ` -- When a merchant opens a new form, the first text field should be in a focused state. -- If the merchant is actively focused in a text field, then the keyboard should come up and the label should move to the top of the field. -- If focus goes away from the text field, then the keyboard should hide. -- Text fields always take up the full screen width. -- Text fields don’t change height. If text entered is longer than the width of the text field, then the oldest text on the left should be hidden to make room. -- When it makes sense, provide autocomplete options (for example, entering an address). - `, +- **Set initial focus appropriately:** When merchants open a new form, set focus on the first text field automatically to streamline data entry and reduce the number of interactions required to begin input. +- **Write clear and concise labels:** Write labels in sentence case and keep them brief. Use consistent terminology for similar fields throughout the app to create a predictable and familiar experience for merchants. +- **Indicate required fields clearly:** When a text field is required for form submission, use the \`required\` property and display a "Required" indicator. Implement validation logic in your \`onChange\` callback to check empty values and display errors. +- **Provide helpful guidance with helpText and placeholder:** Use \`helpText\` for explain content expectations, formatting requirements, or character limits. Use placeholder text to provide examples of the expected content format or structure. +- **Support autocomplete when appropriate:** Provide autocomplete options for fields where merchants commonly enter predictable values, such as addresses, product names, or customer information. +- **Implement character limits appropriately:** Set \`maxLength\` to prevent excessively long input that might cause display or processing issues. Provide feedback about character limits in the \`helpText\`, especially when users are approaching the limit. +- **Use action buttons for enhanced functionality:** Use the \`action\` property to provide helpful actions like "Clear Field," "Generate Code," or "Use Default." This enhances usability by providing quick access to common text operations. + `, }, { type: 'Generic', - anchorLink: 'content-guidelines', - title: 'Content Guidelines', + anchorLink: 'limitations', + title: 'Limitations', sectionContent: ` -- If a text field is required, then it should indicate \`Required\`. -- Label titles should be brief and written in sentence case. -- Use the same terms for similar label titles throughout the app. - `, +- \`TextField\` provides single-line text input only—multi-line text entry requires the \`TextArea\` component. +- The \`required\` property adds semantic meaning only—it doesn't trigger automatic error display or validation, so you must implement validation logic manually. +- Action buttons are limited to simple press callbacks—complex action workflows require custom implementation or additional components. + `, }, ], }; diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/Tile.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/Tile.doc.ts index a559976c38..9d1f26af31 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/Tile.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/Tile.doc.ts @@ -6,28 +6,57 @@ const generateCodeBlockForTile = (title: string, fileName: string) => const data: ReferenceEntityTemplateSchema = { name: 'Tile', - description: `Tiles are customizable buttons that allow staff to complete actions quickly. Think of them as shortcuts--adding a 10% discount to an order, for example. Tiles provide contextual information and let merchants quickly access workflows, actions, and information from the smart grid and the top of detail pages. They’re dynamic and can change based on surrounding context, such as what’s in the cart. - > Note: - > The appearance of \`destructive\` has been updated as of POS 10.0.0 to appear as an active state.`, + description: + 'The `Tile` component displays interactive buttons for the POS smart grid that allow merchants to complete actions quickly. Tiles serve as customizable shortcuts that provide contextual information and enable merchants to quickly access workflows, actions, and information from the smart grid.\n\nTiles are dynamic components that can change their appearance, content, and enabled state based on surrounding context such as cart contents, device conditions, or runtime state. They support tap interactions, visual feedback, and can display contextual information through titles, subtitles, and badge values.', isVisualComponent: true, type: 'component', definitions: [ { - title: 'Tile', - description: '', + title: 'Properties', + description: + 'Configure the following properties on the `Tile` component.', type: 'TileProps', }, ], - category: 'Components', + category: 'UI components', + subCategory: 'Actions', related: [], thumbnail: 'tile-thumbnail.png', defaultExample: { image: 'tile-default.png', codeblock: generateCodeBlockForTile( - 'Render a tile on smart grid', + 'Create a smart grid tile', 'default.example', ), + description: + 'Display an interactive button on the POS smart grid for quick actions. This example shows a Tile that provides customizable shortcuts with contextual information, titles, subtitles, and badge values, enabling merchants to quickly access workflows and complete actions from the smart grid.', }, + subSections: [ + { + type: 'Generic', + anchorLink: 'best-practices', + title: 'Best practices', + sectionContent: ` +- **Provide contextual subtitles:** Show dynamic information like cart totals, eligibility requirements, current status, or helpful context. Subtitles should complement the title by providing additional details staff need before taking action. +- **Use meaningful badge values:** Display counts that represent actionable items or important status information like pending notifications, items requiring action, or error counts. Badge values work best when they represent actionable information rather than purely informational counts. +- **Design tiles as workflow entry points:** Use tiles primarily to launch modal experiences using \`api.action.presentModal()\` rather than performing complex operations directly. Store contextual data before presenting modals. +- **Update properties efficiently:** Dynamically enable or disable tiles based on cart state, user permissions, or business rules. Only call \`updateProps()\` when displayed values actually change, and batch multiple property updates into single calls. + `, + }, + { + type: 'Generic', + anchorLink: 'limitations', + title: 'Limitations', + sectionContent: ` +- Each POS UI extension can only render one \`Tile\` component. +- Badge values must be numeric-string or text badges aren't supported. +- Custom icons, images, or visual styling beyond built-in properties aren't supported. +- Tile size and layout is determined by the smart grid and can't be customized. +- The \`Tile\` component is limited to tap interactions only. There's no support for long press, swipe, or other gestures. +- Title and subtitle text must be plain strings-no HTML, markdown, or rich text formatting. + `, + }, + ], }; export default data; diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/TimeField.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/TimeField.doc.ts index a272fc177c..6b65290ac4 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/TimeField.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/TimeField.doc.ts @@ -4,33 +4,55 @@ import {generateCodeBlock} from '../helpers/generateCodeBlock'; const data: ReferenceEntityTemplateSchema = { name: 'TimeField', description: - 'A component that enables users to open a dialog and select a time through a text input.', + 'The `TimeField` component captures time input from merchants with a consistent interface for time selection and proper validation. Use it to collect time information in scheduling, booking, or data entry workflows.\n\nThe component supports both 12-hour and 24-hour time formats based on locale settings, with built-in validation to ensure valid time entries. It includes features like time picker integration, keyboard shortcuts, and formatted display to streamline time entry for scheduling, appointment booking, and time-sensitive operations in retail environments.\n\n`TimeField` components respects merchant locale settings for default time format preferences while allowing manual override for specific use cases that require alternative formats.', isVisualComponent: true, type: 'component', definitions: [ { - title: 'TimeField', - description: '', + title: 'Properties', + description: + 'Configure the following properties on the `TimeField` component.', type: 'TimeFieldProps', }, ], - category: 'Components', + category: 'UI components', + subCategory: 'Forms', related: [], defaultExample: { image: 'time-field-default.png', - codeblock: generateCodeBlock('Time input', 'time-field', 'time-input'), + codeblock: generateCodeBlock( + 'Capture time input with validation', + 'time-field', + 'time-input', + ), + description: + 'Collect time information using a text-based input field with built-in validation. This example shows a TimeField that supports both 12-hour and 24-hour formats based on locale, with time picker integration and keyboard shortcuts for scheduling and time-sensitive operations.', }, + thumbnail: 'time-field-thumbnail.png', subSections: [ { type: 'Generic', - anchorLink: 'guidelines', - title: 'Guidelines', + anchorLink: 'best-practices', + title: 'Best practices', sectionContent: ` -- Use a smart default time for common selections. +- **Provide clear labels for time context:** Use specific labels that indicate what time is being requested, like specific examples rather than generic "Time." This helps users understand the context and purpose. +- **Offer helpful guidance with helpText:** Use the \`helpText\` property to explain time constraints, business hours, or format expectations. For example, "Business hours only (9 AM - 5 PM)" or "Must be a future time." +- **Implement proper time validation:** Use the \`error\` property to display validation messages when users enter invalid times or times outside acceptable ranges. Provide clear, actionable error messages that help users correct their input. +- **Add action buttons for time operations:** Use the \`action\` property to provide helpful actions like "Set to Now," "Clear Time," or "Use Business Hours." This enhances usability by providing quick access to common time operations. +- **Handle focus events for time picker coordination:** Use \`onFocus\` and \`onBlur\` callbacks to coordinate with \`TimePicker\` components or other time selection interfaces. This is useful for showing/hiding time pickers or managing related form fields. + `, + }, + { + type: 'Generic', + anchorLink: 'limitations', + title: 'Limitations', + sectionContent: ` +- \`TimeField\` provides text-based time input—for visual time selection with clock or spinner interfaces, use the \`TimePicker\` component which offers interactive time selection. +- The \`is24Hour\` property only affects Android devices—other platforms may use their system-level time format preferences regardless of this setting. +- Action buttons are limited to simple press callbacks—complex action workflows require custom implementation or additional components. `, }, ], - thumbnail: 'time-field-thumbnail.png', }; export default data; diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/TimePicker.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/TimePicker.doc.ts index b001539ba0..a960fb410a 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/TimePicker.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/TimePicker.doc.ts @@ -7,23 +7,56 @@ const generateCodeBlockForTimePicker = (title: string, fileName: string) => const data: ReferenceEntityTemplateSchema = { name: 'TimePicker', - description: 'A component used to select a time through a dialog.', + description: + 'The `TimePicker` component allows merchants to select a specific time using an interactive picker interface. Use it to provide visual time selection for improved user experience and reduced input errors.\n\n`TimePicker` offers a more visual and touch-friendly alternative to text-based time input, making time selection faster and more accurate. The picker interface provides an intuitive way to select hours and minutes through an interactive interface.', isVisualComponent: true, type: 'component', definitions: [ { - title: 'TimePicker', - description: '', + title: 'Properties', + description: + 'Configure the following properties on the `TimePicker` component.', type: 'TimePickerProps', }, ], - category: 'Components', + category: 'UI components', + subCategory: 'Forms', related: [], thumbnail: 'time-picker-thumbnail.png', defaultExample: { image: 'time-picker-default.png', - codeblock: generateCodeBlockForTimePicker('TimePicker', 'default.example'), + codeblock: generateCodeBlockForTimePicker( + 'Select time with a picker', + 'default.example', + ), + description: + 'Enable time selection using an interactive picker interface. This example demonstrates a TimePicker that provides a visual, touch-friendly way to select hours and minutes, making time selection faster and more accurate than text-based input for scheduling workflows.', }, + subSections: [ + { + type: 'Generic', + anchorLink: 'best-practices', + title: 'Best practices', + sectionContent: ` +- **Choose appropriate input modes for your platform:** Use \`'inline'\` mode (clock) on Android when users benefit from seeing a clock interface. iOS only supports \`'spinner'\` mode, so design your time selection experience to work well with spinners across all platforms. +- **Configure time format for Android users:** Use the \`is24Hour\` property to control whether Android devices display times in 24-hour or 12-hour format. Set this based on your target audience's preferences and regional conventions. This property only affects Android devices. +- **Handle time selection with onChange:** Implement the \`onChange\` callback to capture selected times and update your application state accordingly. This callback receives the selected time string that you can use to update UI or trigger related actions. +- **Default to current time thoughtfully:** The picker defaults to the current time when no \`selected\` value is provided. If you need a different starting time or want to guide users to a specific time period, explicitly set the \`selected\` property. +- **Provide clear triggers for showing the picker:** Since visibility is controlled by \`visibleState\`, ensure you have clear UI elements like buttons or field interactions that toggle the picker visibility. Users should understand how to open and close the time picker. + `, + }, + { + type: 'Generic', + anchorLink: 'limitations', + title: 'Limitations', + sectionContent: ` +- \`TimePicker\` requires external visibility state management through the \`visibleState\` tuple—automatic show/hide behavior based on field focus is not built-in. +- The \`inputMode\` property has platform limitations—iOS only supports spinner mode regardless of the \`inputMode\` setting, which may affect cross-platform consistency. +- The \`is24Hour\` property only affects Android devices—iOS and other platforms use their system-level time format preferences regardless of this setting. +- The component provides time selection but doesn't include field labels, help text, or error messaging—combine with other UI elements or text components to provide complete form field experiences. + `, + }, + ], }; export default data; diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.customer-details.action.menu-item.render.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.customer-details.action.menu-item.render.doc.ts index 13cde8a019..8f0f43735a 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.customer-details.action.menu-item.render.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.customer-details.action.menu-item.render.doc.ts @@ -5,31 +5,21 @@ import {ExtensionTargetType} from '../types/ExtensionTargetType'; const data: ReferenceEntityTemplateSchema = { name: ExtensionTargetType.PosCustomerDetailsActionMenuItemRender, description: - 'A static extension target that renders as a menu item on the customer details screen', + 'Renders a single interactive button component as a menu item in the customer details action menu. Use this target for customer-specific operations like applying customer discounts, processing loyalty redemptions, or launching profile update workflows.' + + '\n\nExtensions at this target can access the customer identifier through the Customer API to perform customer-specific operations. Menu items typically invoke `api.action.presentModal()` to launch the companion modal for complete customer workflows.', defaultExample: { codeblock: generateCodeBlock( - 'Menu item', + 'Create a customer details action menu item', 'targets', 'customer-details-menu-item', ), + description: + 'Add an interactive menu item to the customer details action menu for customer-specific operations. This example shows how to create a menu item that accesses customer data and launches modal workflows for tasks like applying discounts, processing loyalty redemptions, or updating customer profiles.', }, category: 'Targets', subCategory: 'Customer details', isVisualComponent: false, - related: [ - { - name: ExtensionTargetType.PosCustomerDetailsActionRender, - url: '/docs/api/pos-ui-extensions/targets/pos-customer-details-action-render', - }, - { - name: ExtensionTargetType.PosCustomerDetailsBlockRender, - url: '/docs/api/pos-ui-extensions/targets/pos-customer-details-block-render', - }, - { - name: 'Customer API', - url: '/docs/api/pos-ui-extensions/apis/customer-api', - }, - ], + related: [], type: 'Target', }; diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.customer-details.action.render.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.customer-details.action.render.doc.ts index 12488d985b..40678270e9 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.customer-details.action.render.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.customer-details.action.render.doc.ts @@ -5,31 +5,21 @@ import {ExtensionTargetType} from '../types/ExtensionTargetType'; const data: ReferenceEntityTemplateSchema = { name: ExtensionTargetType.PosCustomerDetailsActionRender, description: - 'A full-screen extension target that renders when a `pos.customer-details.action.menu-item.render` target calls for it', + 'Renders a full-screen modal interface launched from customer details menu items. Use this target for complex customer workflows that require forms, multi-step processes, or detailed information displays beyond what a simple button can provide.' + + '\n\nExtensions at this target have access to customer data through the Customer API and support workflows with multiple screens, navigation, and interactive components.', defaultExample: { codeblock: generateCodeBlock( - 'Action', + 'Create a customer details action modal', 'targets', 'customer-details-action', ), + description: + 'Build a full-screen modal launched from customer details menu items for complex customer workflows. This example demonstrates creating modals with multiple screens and interactive components, enabling forms, multi-step processes, or detailed information displays with full customer data access.', }, category: 'Targets', subCategory: 'Customer details', isVisualComponent: false, - related: [ - { - name: ExtensionTargetType.PosCustomerDetailsActionMenuItemRender, - url: '/docs/api/pos-ui-extensions/targets/pos-customer-details-action-menu-item-render', - }, - { - name: ExtensionTargetType.PosCustomerDetailsBlockRender, - url: '/docs/api/pos-ui-extensions/targets/pos-customer-details-block-render', - }, - { - name: 'Customer API', - url: '/docs/api/pos-ui-extensions/apis/customer-api', - }, - ], + related: [], type: 'Target', }; diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.customer-details.block.render.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.customer-details.block.render.doc.ts index 9d477d0e05..d73fcbed02 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.customer-details.block.render.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.customer-details.block.render.doc.ts @@ -4,27 +4,22 @@ import {ExtensionTargetType} from '../types/ExtensionTargetType'; const data: ReferenceEntityTemplateSchema = { name: ExtensionTargetType.PosCustomerDetailsBlockRender, - description: 'Renders a custom section within customer details screen', + description: + 'Renders a custom information section within the customer details screen. Use this target for displaying supplementary customer data like loyalty status, points balance, or personalized information alongside standard customer details.' + + '\n\nExtensions at this target appear as persistent blocks within the customer details interface and support interactive elements that can launch modal workflows using `api.action.presentModal()` for more complex customer operations.', defaultExample: { codeblock: generateCodeBlock( - 'Block', + 'Add a customer details block', 'targets', 'pos-customer-details-block-render', ), + description: + 'Display custom information within the customer details screen as a persistent block. This example shows how to create blocks that show supplementary customer data like loyalty status, points balance, or personalized information with interactive elements that can launch modal workflows.', }, category: 'Targets', subCategory: 'Customer details', isVisualComponent: false, - related: [ - { - name: ExtensionTargetType.PosCustomerDetailsActionMenuItemRender, - url: '/docs/api/pos-ui-extensions/targets/pos-customer-details-action-menu-item-render', - }, - { - name: ExtensionTargetType.PosCustomerDetailsActionRender, - url: '/docs/api/pos-ui-extensions/targets/pos-customer-details-action-render', - }, - ], + related: [], type: 'Target', }; diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.draft-order-details.action.menu-item.render.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.draft-order-details.action.menu-item.render.doc.ts index 8a2e55b73e..77356f8658 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.draft-order-details.action.menu-item.render.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.draft-order-details.action.menu-item.render.doc.ts @@ -5,27 +5,21 @@ import {ExtensionTargetType} from '../types/ExtensionTargetType'; const data: ReferenceEntityTemplateSchema = { name: ExtensionTargetType.PosDraftOrderDetailsActionMenuItemRender, description: - 'A static extension target that renders as a menu item on the draft order details screen', + 'Renders a single interactive button component as a menu item in the draft order details action menu. Use this target for draft order-specific operations like sending invoices, updating payment status, or launching custom workflow processes for pending orders.' + + '\n\nExtensions at this target can access draft order information including order ID, name, and associated customer through the Draft Order API. Menu items typically invoke `api.action.presentModal()` to launch the companion modal for complete draft order workflows.', defaultExample: { codeblock: generateCodeBlock( - 'Menu item', + 'Create a draft order details action menu item', 'targets', 'pos-draft-order-details-action-menu-item', ), + description: + 'Add an interactive menu item to the draft order details action menu for draft order-specific operations. This example shows how to create a menu item that accesses draft order information and launches modal workflows for tasks like sending invoices, updating payment status, or custom order processes.', }, category: 'Targets', subCategory: 'Draft order details', isVisualComponent: false, - related: [ - { - name: ExtensionTargetType.PosDraftOrderDetailsActionRender, - url: '/docs/api/pos-ui-extensions/targets/pos-draft-order-details-action-render', - }, - { - name: ExtensionTargetType.PosDraftOrderDetailsBlockRender, - url: '/docs/api/pos-ui-extensions/targets/pos-draft-order-details-block-render', - }, - ], + related: [], type: 'Target', }; diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.draft-order-details.action.render.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.draft-order-details.action.render.doc.ts index 98612f3ef4..a34680536a 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.draft-order-details.action.render.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.draft-order-details.action.render.doc.ts @@ -5,31 +5,21 @@ import {ExtensionTargetType} from '../types/ExtensionTargetType'; const data: ReferenceEntityTemplateSchema = { name: ExtensionTargetType.PosDraftOrderDetailsActionRender, description: - 'A full-screen extension target that renders when a `pos.draft-order-details.action.render` target calls for it', + 'Renders a full-screen modal interface launched from draft order details menu items. Use this target for complex draft order workflows that require forms, multi-step processes, or detailed information displays beyond what a simple button can provide.' + + '\n\nExtensions at this target have access to draft order data through the Draft Order API and support workflows with multiple screens, navigation, and interactive components.', defaultExample: { codeblock: generateCodeBlock( - 'Draft order details action', + 'Create a draft order details action modal', 'targets', 'pos-draft-order-details-action', ), + description: + 'Build a full-screen modal launched from draft order details menu items for complex draft order workflows. This example demonstrates creating modals with multiple screens and interactive components, enabling forms, multi-step processes, or detailed information displays with full draft order data access.', }, category: 'Targets', subCategory: 'Draft order details', isVisualComponent: false, - related: [ - { - name: ExtensionTargetType.PosDraftOrderDetailsActionMenuItemRender, - url: '/docs/api/pos-ui-extensions/targets/pos-draft-order-details-action-menu-item-render', - }, - { - name: ExtensionTargetType.PosDraftOrderDetailsBlockRender, - url: '/docs/api/pos-ui-extensions/targets/pos-draft-order-details-block-render', - }, - { - name: 'Draft order details API', - url: '/docs/api/pos-ui-extensions/apis/draft-order-api', - }, - ], + related: [], type: 'Target', }; diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.draft-order-details.block.render.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.draft-order-details.block.render.doc.ts index 3c385dfdf0..e5c74bf6b2 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.draft-order-details.block.render.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.draft-order-details.block.render.doc.ts @@ -5,27 +5,21 @@ import {ExtensionTargetType} from '../types/ExtensionTargetType'; const data: ReferenceEntityTemplateSchema = { name: ExtensionTargetType.PosDraftOrderDetailsBlockRender, description: - 'Renders a custom section within the native draft order details screen', + 'Renders a custom information section within the draft order details screen. Use this target for displaying supplementary order information like processing status, payment status, or workflow indicators alongside standard draft order details.' + + '\n\nExtensions at this target appear as persistent blocks within the draft order interface and support interactive elements that can launch modal workflows using `api.action.presentModal()` for more complex draft order operations.', defaultExample: { codeblock: generateCodeBlock( - 'Block', + 'Add a draft order details block', 'targets', 'pos-draft-order-details-block-render', ), + description: + 'Display custom information within the draft order details screen as a persistent block. This example shows how to create blocks that show supplementary order information like processing status, payment status, or workflow indicators with interactive elements.', }, category: 'Targets', subCategory: 'Draft order details', isVisualComponent: false, - related: [ - { - name: ExtensionTargetType.PosDraftOrderDetailsActionMenuItemRender, - url: '/docs/api/pos-ui-extensions/targets/pos-draft-order-details-action-menu-item-render', - }, - { - name: ExtensionTargetType.PosDraftOrderDetailsActionRender, - url: '/docs/api/pos-ui-extensions/targets/pos-draft-order-details-action-render', - }, - ], + related: [], type: 'Target', }; diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.home.modal.render.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.home.modal.render.doc.ts index b131c75ba3..3d00bfbdef 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.home.modal.render.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.home.modal.render.doc.ts @@ -4,19 +4,21 @@ import {generateCodeBlock} from '../helpers/generateCodeBlock'; const data: ReferenceEntityTemplateSchema = { name: 'pos.home.modal.render', description: - 'A full-screen extension target that renders when a `pos.home.tile.render` target calls for it', + 'Renders a full-screen modal interface launched from smart grid tiles. The modal appears when users tap a companion tile. Use this target for complete workflow experiences that require more space and functionality than the tile interface provides, such as multi-step processes, detailed information displays, or complex user interactions.' + + '\n\nExtensions at this target support full navigation hierarchies with multiple screens, scroll views, and interactive components to handle sophisticated workflows.', defaultExample: { - codeblock: generateCodeBlock('Modal', 'targets', 'pos-home-modal-render'), + codeblock: generateCodeBlock( + 'Create a full-screen modal from a tile', + 'targets', + 'pos-home-modal-render', + ), + description: + 'Build a full-screen modal interface launched from smart grid tiles. This example demonstrates creating a modal that appears when merchants tap a tile, supporting complete workflows with multiple screens, scroll views, and interactive components for sophisticated tasks.', }, category: 'Targets', - subCategory: 'Smart grid', + subCategory: 'Home screen (smart grid)', isVisualComponent: false, - related: [ - { - name: 'pos.home.tile.render', - url: '/docs/api/pos-ui-extensions/targets/pos-home-tile-render', - }, - ], + related: [], type: 'Target', }; diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.home.tile.render.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.home.tile.render.doc.ts index e8119cb8d3..2e82f550cc 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.home.tile.render.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.home.tile.render.doc.ts @@ -3,19 +3,22 @@ import {generateCodeBlock} from '../helpers/generateCodeBlock'; const data: ReferenceEntityTemplateSchema = { name: 'pos.home.tile.render', - description: 'A static extension target that renders as a smart grid tile', + description: + "Renders a single interactive tile component on the POS home screen's smart grid. The tile appears once during home screen initialization and remains persistent until navigation occurs. Use this target for high-frequency actions, status displays, or entry points to workflows that merchants need daily." + + '\n\nExtensions at this target can dynamically update properties like enabled state and badge values in response to cart changes or device conditions. Tiles typically invoke `api.action.presentModal()` to launch the companion modal for complete workflows.', defaultExample: { - codeblock: generateCodeBlock('Tile', 'targets', 'pos-home-tile-render'), + codeblock: generateCodeBlock( + 'Create a smart grid tile', + 'targets', + 'pos-home-tile-render', + ), + description: + 'Add an interactive tile to the POS home screen smart grid for high-frequency actions. This example shows how to create a persistent tile that can dynamically update its enabled state and badge values, providing merchants with quick access to daily workflows and status displays.', }, category: 'Targets', - subCategory: 'Smart grid', + subCategory: 'Home screen (smart grid)', isVisualComponent: false, - related: [ - { - name: 'pos.home.modal.render', - url: '/docs/api/pos-ui-extensions/targets/pos-home-modal-render', - }, - ], + related: [], type: 'Target', }; diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.order-details.action.menu-item.render.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.order-details.action.menu-item.render.doc.ts index 6af5e7806f..2369e40e9b 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.order-details.action.menu-item.render.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.order-details.action.menu-item.render.doc.ts @@ -5,27 +5,21 @@ import {ExtensionTargetType} from '../types/ExtensionTargetType'; const data: ReferenceEntityTemplateSchema = { name: ExtensionTargetType.PosOrderDetailsActionMenuItemRender, description: - 'A static extension target that renders as a menu item on the order details screen', + 'Renders a single interactive button component as a menu item in the order details action menu. Use this target for order-specific operations like reprints, refunds, exchanges, or launching fulfillment workflows.' + + '\n\nExtensions at this target can access the order identifier through the Order API to perform order-specific operations. Menu items typically invoke `api.action.presentModal()` to launch the companion modal for complete order workflows.', defaultExample: { codeblock: generateCodeBlock( - 'Order details action menu item', + 'Create an order details action menu item', 'targets', 'pos-order-details-action-menu-item-render', ), + description: + 'Add an interactive menu item to the order details action menu for order-specific operations. This example shows how to create a menu item that accesses order data and launches modal workflows for tasks like reprints, refunds, exchanges, or fulfillment processes.', }, category: 'Targets', subCategory: 'Order details', isVisualComponent: false, - related: [ - { - name: ExtensionTargetType.PosOrderDetailsActionRender, - url: '/docs/api/pos-ui-extensions/targets/pos-order-details-action-render', - }, - { - name: ExtensionTargetType.PosOrderDetailsBlockRender, - url: '/docs/api/pos-ui-extensions/targets/pos-order-details-block-render', - }, - ], + related: [], type: 'Target', }; diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.order-details.action.render.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.order-details.action.render.doc.ts index def61206f9..e8bdac4723 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.order-details.action.render.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.order-details.action.render.doc.ts @@ -5,27 +5,21 @@ import {ExtensionTargetType} from '../types/ExtensionTargetType'; const data: ReferenceEntityTemplateSchema = { name: ExtensionTargetType.PosOrderDetailsActionRender, description: - 'A full-screen extension target that renders when a `pos.order-details.action.menu-item.render` target calls for it', + 'Renders a full-screen modal interface launched from order details menu items. Use this target for complex order workflows that require forms, multi-step processes, or detailed information displays beyond what a simple button can provide.' + + '\n\nExtensions at this target have access to order data through the Order API and support workflows with multiple screens, navigation, and interactive components.', defaultExample: { codeblock: generateCodeBlock( - 'Order details action', + 'Create an order details action modal', 'targets', 'pos-order-details-action-render', ), + description: + 'Build a full-screen modal launched from order details menu items for complex order workflows. This example demonstrates creating modals with multiple screens and interactive components, enabling forms, multi-step processes, or detailed information displays with full order data access.', }, category: 'Targets', subCategory: 'Order details', isVisualComponent: false, - related: [ - { - name: ExtensionTargetType.PosOrderDetailsActionMenuItemRender, - url: '/docs/api/pos-ui-extensions/targets/pos-order-details-action-menu-item-render', - }, - { - name: ExtensionTargetType.PosOrderDetailsBlockRender, - url: '/docs/api/pos-ui-extensions/targets/pos-order-details-block-render', - }, - ], + related: [], type: 'Target', }; diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.order-details.block.render.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.order-details.block.render.doc.ts index e6e2ad3eca..66f07aa0cb 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.order-details.block.render.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.order-details.block.render.doc.ts @@ -5,27 +5,21 @@ import {ExtensionTargetType} from '../types/ExtensionTargetType'; const data: ReferenceEntityTemplateSchema = { name: ExtensionTargetType.PosOrderDetailsBlockRender, description: - 'Renders a custom section within the native order details screen', + 'Renders a custom information section within the order details screen. Use this target for displaying supplementary order data like fulfillment status, tracking numbers, or custom order analytics alongside standard order details.' + + '\n\nExtensions at this target appear as persistent blocks within the order details interface and support interactive elements that can launch modal workflows using `api.action.presentModal()` for more complex order operations.', defaultExample: { codeblock: generateCodeBlock( - 'Block', + 'Add an order details block', 'targets', 'pos-order-details-block-render', ), + description: + 'Display custom information within the order details screen as a persistent block. This example shows how to create blocks that show supplementary order data like fulfillment status, tracking numbers, or custom analytics with interactive elements that can launch modal workflows.', }, category: 'Targets', subCategory: 'Order details', isVisualComponent: false, - related: [ - { - name: ExtensionTargetType.PosOrderDetailsActionMenuItemRender, - url: '/docs/api/pos-ui-extensions/targets/pos-order-details-action-menu-item-render', - }, - { - name: ExtensionTargetType.PosOrderDetailsActionRender, - url: '/docs/api/pos-ui-extensions/targets/pos-order-details-action-render', - }, - ], + related: [], type: 'Target', }; diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.product-details.action.menu-item.render.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.product-details.action.menu-item.render.doc.ts index 38cbed2090..bb8613337c 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.product-details.action.menu-item.render.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.product-details.action.menu-item.render.doc.ts @@ -5,31 +5,21 @@ import {ExtensionTargetType} from '../types/ExtensionTargetType'; const data: ReferenceEntityTemplateSchema = { name: ExtensionTargetType.PosProductDetailsActionMenuItemRender, description: - 'A static extension target that renders as a menu item on the product details screen', + 'Renders a single interactive button component as a menu item in the product details action menu. Use this target for product-specific operations like inventory adjustments, product analytics, or integration with external product management systems.' + + '\n\nExtensions at this target can access the product identifier through the Product API to perform product-specific operations. Menu items typically invoke `api.action.presentModal()` to launch the companion modal for complete product workflows.', defaultExample: { codeblock: generateCodeBlock( - 'Menu item', + 'Create a product details action menu item', 'targets', 'product-details-menu-item', ), + description: + 'Add an interactive menu item to the product details action menu for product-specific operations. This example shows how to create a menu item that accesses product data and launches modal workflows for tasks like inventory adjustments, product analytics, or external system integrations.', }, category: 'Targets', subCategory: 'Product details', isVisualComponent: false, - related: [ - { - name: ExtensionTargetType.PosProductDetailsActionRender, - url: '/docs/api/pos-ui-extensions/targets/pos-product-details-action-render', - }, - { - name: ExtensionTargetType.PosProductDetailsBlockRender, - url: '/docs/api/pos-ui-extensions/targets/pos-product-details-block-render', - }, - { - name: 'ProductAPI', - url: '/docs/api/pos-ui-extensions/apis/product-api', - }, - ], + related: [], type: 'Target', }; diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.product-details.action.render.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.product-details.action.render.doc.ts index 05e038afc3..e4d3a272b3 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.product-details.action.render.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.product-details.action.render.doc.ts @@ -5,27 +5,21 @@ import {ExtensionTargetType} from '../types/ExtensionTargetType'; const data: ReferenceEntityTemplateSchema = { name: ExtensionTargetType.PosProductDetailsActionRender, description: - 'A full-screen extension target that renders when a `pos.product-details.action.menu-item.render` target calls for it', + 'Renders a full-screen modal interface launched from product details menu items. Use this target for complex product workflows that require forms, multi-step processes, or detailed information displays beyond what a simple button can provide.' + + '\n\nExtensions at this target have access to product and cart data through the Product API and support workflows with multiple screens, navigation, and interactive components.', defaultExample: { - codeblock: generateCodeBlock('Action', 'targets', 'product-details-action'), + codeblock: generateCodeBlock( + 'Create a product details action modal', + 'targets', + 'product-details-action', + ), + description: + 'Build a full-screen modal launched from product details menu items for complex product workflows. This example demonstrates creating modals with multiple screens and interactive components, enabling forms, multi-step processes, or detailed information displays with full product and cart data access.', }, category: 'Targets', subCategory: 'Product details', isVisualComponent: false, - related: [ - { - name: ExtensionTargetType.PosProductDetailsActionMenuItemRender, - url: '/docs/api/pos-ui-extensions/targets/pos-product-details-action-menu-item-render', - }, - { - name: ExtensionTargetType.PosProductDetailsBlockRender, - url: '/docs/api/pos-ui-extensions/targets/pos-product-details-block-render', - }, - { - name: 'ProductAPI', - url: '/docs/api/pos-ui-extensions/apis/product-api', - }, - ], + related: [], type: 'Target', }; diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.product-details.block.render.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.product-details.block.render.doc.ts index df2186b9cd..7b9eb78455 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.product-details.block.render.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.product-details.block.render.doc.ts @@ -4,31 +4,22 @@ import {ExtensionTargetType} from '../types/ExtensionTargetType'; const data: ReferenceEntityTemplateSchema = { name: ExtensionTargetType.PosProductDetailsBlockRender, - description: 'Renders a custom section within the product details screen', + description: + 'Renders a custom information section within the product details screen. Use this target for displaying supplementary product data like detailed specifications, inventory status, or related product recommendations alongside standard product details.' + + '\n\nExtensions at this target appear as persistent blocks within the product details interface and support interactive elements that can launch modal workflows using `api.action.presentModal()` for more complex product operations.', defaultExample: { codeblock: generateCodeBlock( - 'Block', + 'Add a product details block', 'targets', 'pos-product-details-block-render', ), + description: + 'Display custom information within the product details screen as a persistent block. This example shows how to create blocks that show supplementary product data like detailed specifications, inventory status, or related recommendations with interactive elements.', }, category: 'Targets', subCategory: 'Product details', isVisualComponent: false, - related: [ - { - name: ExtensionTargetType.PosProductDetailsActionMenuItemRender, - url: '/docs/api/pos-ui-extensions/targets/pos-product-details-action-menu-item-render', - }, - { - name: ExtensionTargetType.PosProductDetailsActionRender, - url: '/docs/api/pos-ui-extensions/targets/pos-product-details-action-render', - }, - { - name: 'ProductAPI', - url: '/docs/api/pos-ui-extensions/apis/product-api', - }, - ], + related: [], type: 'Target', }; diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.purchase.post.action.menu-item.render.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.purchase.post.action.menu-item.render.doc.ts index 79c48cb90b..a72ad6e760 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.purchase.post.action.menu-item.render.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.purchase.post.action.menu-item.render.doc.ts @@ -5,27 +5,21 @@ import {ExtensionTargetType} from '../types/ExtensionTargetType'; const data: ReferenceEntityTemplateSchema = { name: ExtensionTargetType.PosPurchasePostActionMenuItemRender, description: - 'A static extension target that renders as a menu item on the post-purchase screen', + 'Renders a single interactive button component as a menu item in the post-purchase action menu. Use this target for post-purchase operations like sending receipts, collecting customer feedback, or launching follow-up workflows after completing a sale.' + + '\n\nExtensions at this target can access the order identifier through the Order API to perform purchase-specific operations. Menu items typically invoke `api.action.presentModal()` to launch the companion modal for complete post-purchase workflows.', defaultExample: { codeblock: generateCodeBlock( - 'Menu item', + 'Create a post-purchase action menu item', 'targets', 'pos-purchase-post-action-menu-item-render', ), + description: + 'Add an interactive menu item to the post-purchase action menu for operations after completing a sale. This example shows how to create a menu item that accesses order data and launches modal workflows for tasks like sending receipts, collecting feedback, or follow-up processes.', }, category: 'Targets', subCategory: 'Post-purchase', isVisualComponent: false, - related: [ - { - name: ExtensionTargetType.PosPurchasePostActionRender, - url: '/docs/api/pos-ui-extensions/targets/pos-purchase-post-action-render', - }, - { - name: ExtensionTargetType.PosPurchasePostBlockRender, - url: '/docs/api/pos-ui-extensions/targets/pos-purchase-post-block-render', - }, - ], + related: [], type: 'Target', }; diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.purchase.post.action.render.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.purchase.post.action.render.doc.ts index 02239fd602..1c53287a80 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.purchase.post.action.render.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.purchase.post.action.render.doc.ts @@ -5,27 +5,21 @@ import {ExtensionTargetType} from '../types/ExtensionTargetType'; const data: ReferenceEntityTemplateSchema = { name: ExtensionTargetType.PosPurchasePostActionRender, description: - 'A full-screen extension target that renders when a `pos.purchase.post.action.menu-item.render` target calls for it', + 'Renders a full-screen modal interface launched from post-purchase menu items. Use this target for complex post-purchase workflows that require forms, multi-step processes, or detailed information displays beyond what a simple button can provide.' + + '\n\nExtensions at this target have access to order data through the Order API and support workflows with multiple screens, navigation, and interactive components.', defaultExample: { codeblock: generateCodeBlock( - 'Action', + 'Create a post-purchase action modal', 'targets', 'pos-purchase-post-action-render', ), + description: + 'Build a full-screen modal launched from post-purchase menu items for complex post-sale workflows. This example demonstrates creating modals with multiple screens and interactive components, enabling forms, multi-step processes, or detailed information displays with full order data access.', }, category: 'Targets', subCategory: 'Post-purchase', isVisualComponent: false, - related: [ - { - name: ExtensionTargetType.PosPurchasePostActionMenuItemRender, - url: '/docs/api/pos-ui-extensions/targets/pos-purchase-post-action-menu-item-render', - }, - { - name: ExtensionTargetType.PosPurchasePostBlockRender, - url: '/docs/api/pos-ui-extensions/targets/pos-purchase-post-block-render', - }, - ], + related: [], type: 'Target', }; diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.purchase.post.block.render.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.purchase.post.block.render.doc.ts index d016405c44..68d37734e6 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.purchase.post.block.render.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.purchase.post.block.render.doc.ts @@ -5,27 +5,21 @@ import {ExtensionTargetType} from '../types/ExtensionTargetType'; const data: ReferenceEntityTemplateSchema = { name: ExtensionTargetType.PosPurchasePostBlockRender, description: - 'Renders a custom section within the native post purchase screen', + 'Renders a custom information section within the post-purchase screen. Use this target for displaying supplementary purchase data like completion status, customer feedback prompts, or next-step workflows alongside standard purchase details.' + + '\n\nExtensions at this target appear as persistent blocks within the post-purchase interface and support interactive elements that can launch modal workflows using `api.action.presentModal()` for more complex post-purchase operations.', defaultExample: { codeblock: generateCodeBlock( - 'Block', + 'Add a post-purchase block', 'targets', 'pos-purchase-post-block-render', ), + description: + 'Display custom information within the post-purchase screen as a persistent block. This example shows how to create blocks that show supplementary purchase data like completion status, customer feedback prompts, or next-step workflows with interactive elements.', }, category: 'Targets', subCategory: 'Post-purchase', isVisualComponent: false, - related: [ - { - name: ExtensionTargetType.PosPurchasePostActionMenuItemRender, - url: '/docs/api/pos-ui-extensions/targets/pos-purchase-post-action-menu-item-render', - }, - { - name: ExtensionTargetType.PosPurchasePostActionRender, - url: '/docs/api/pos-ui-extensions/targets/pos-purchase-post-action-render', - }, - ], + related: [], type: 'Target', }; diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/api/action-api/action-api.ts b/packages/ui-extensions/src/surfaces/point-of-sale/api/action-api/action-api.ts index 800bb8c319..174c9269c3 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/api/action-api/action-api.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/api/action-api/action-api.ts @@ -1,14 +1,12 @@ export interface ActionApiContent { - /** Presents the `action-overlay.render` extension target on top of present view. - * - * For example: if we are calling presentModal() from pos.purchase.post.action.menu-item.render, - * it should present pos.purchase.post.action.render. + /** + * Presents the corresponding action (modal) target on top of the current view as a full-screen modal. For example, calling this method from `pos.purchase.post.action.menu-item.render` presents `pos.purchase.post.action.render`. Use to launch detailed workflows, complex forms, or multi-step processes that require more screen space than simple components provide. */ presentModal(): void; } /** - * Access the Action API to present your app in a full screen modal. + * The `ActionApi` object provides methods for presenting modal interfaces. Access these methods through `api.action` to launch full-screen modal experiences. */ export interface ActionApi { action: ActionApiContent; diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/api/cart-api/cart-api.ts b/packages/ui-extensions/src/surfaces/point-of-sale/api/cart-api/cart-api.ts index 88fab02c9c..ad80fcf40c 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/api/cart-api/cart-api.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/api/cart-api/cart-api.ts @@ -9,7 +9,7 @@ import type { } from '../types/cart'; /** - * Access and modify the merchant’s current cart. + * The `CartApi` object provides access to cart management functionality and real-time cart state monitoring. Access these properties through `api.cart` to interact with the current POS cart. */ export interface CartApi { cart: CartApiContent; @@ -26,19 +26,25 @@ export type DiscountType = | 'PriceOverride' | 'Code'; +/** + * Defines the type of discount applied at the cart level. Specifies whether the discount is percentage-based, fixed amount, or discount code redemption. + */ export type CartDiscountType = 'Percentage' | 'FixedAmount' | 'Code'; +/** + * Defines the type of discount applied to individual line items. Specifies whether the discount is percentage-based or a fixed amount reduction. + */ export type LineItemDiscountType = 'Percentage' | 'FixedAmount'; export interface CartApiContent { - /** Provides a subscription to POS cart changes. - * Provides an initial value and a callback to subscribe to value changes. Currently supports only one subscription. - * You can utilize `makeStatefulSubscribable` on a `RemoteSubscribable` to implement multiple subscriptions. - * Using `makeStatefulSubscribable` or the corresponding hooks counts as a subscription. + /** + * Subscribes to real-time cart state changes. Provides initial cart value and triggers callbacks on updates. Supports only one active subscription—use `makeStatefulSubscribable` for multiple subscribers. */ subscribable: RemoteSubscribable; - /** Apply a cart level discount + /** + * Apply a cart-level discount with the specified type (`'Percentage'`, `'FixedAmount'`, or `'Code'`), title, and optional amount. For discount codes, omit the `amount` parameter. Enhanced validation ensures proper discount application. + * * @param type the type of discount applied (example: 'Percentage') * @param title the title attributed with the discount * @param amount the percentage or fixed monetary amount deducted with the discount. Pass in `undefined` if using discount codes. @@ -49,57 +55,81 @@ export interface CartApiContent { amount?: string, ): Promise; - /** Add a code discount to the cart + /** + * Apply a discount code to the cart. The system will validate the code and apply the appropriate discount if the code is valid and applicable to the current cart contents. + * * @param code the code for the discount to add to the cart */ addCartCodeDiscount(code: string): Promise; - /** Remove the cart discount */ + /** + * Remove the current cart-level discount. This only affects cart-level discounts and doesn't impact line item discounts or automatic discount eligibility. + */ removeCartDiscount(): Promise; - /** Remove all cart and line item discounts + /** + * Remove all discounts from both the cart and individual line items. Set `disableAutomaticDiscounts` to `true` to prevent automatic discounts from being reapplied after removal. + * * @param disableAutomaticDiscounts Whether or not automatic discounts should be enabled after removing the discounts. */ removeAllDiscounts(disableAutomaticDiscounts: boolean): Promise; - /** Clear the cart */ + /** + * Remove all line items and reset the cart to an empty state. This action can't be undone and will clear all cart contents including line items, discounts, properties, and selling plans. + */ clearCart(): Promise; - /** Set the customer in the cart + /** + * Associate a customer with the current cart using the customer object containing the customer `ID`. This enables customer-specific pricing, discounts, and checkout features with customer data validation. + * * @param customer the customer object to add to the cart */ setCustomer(customer: Customer): Promise; - /** Remove the current customer from the cart */ + /** + * Remove the currently associated customer from the cart, converting it back to a guest cart without customer-specific benefits or information while preserving cart contents. + */ removeCustomer(): Promise; - /** Add a custom sale to the cart + /** + * Add a custom sale item to the cart with specified quantity, title, price, and taxable status. + * * @param customSale the custom sale object to add to the cart */ addCustomSale(customSale: CustomSale): Promise; - /** Add a line item by variant ID to the cart + /** + * Add a product variant to the cart by its numeric `ID` with the specified quantity. + * * @param variantId the product variant's numeric ID to add to the cart * @param quantity the number of this variant to add to the cart */ addLineItem(variantId: number, quantity: number): Promise; - /** Remove the line item at this uuid from the cart + /** + * Remove a specific line item from the cart using its [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier). The line item will be completely removed from the cart along with any associated discounts, properties, or selling plans. + * * @param uuid the uuid of the line item that should be removed */ removeLineItem(uuid: string): Promise; - /** Adds custom properties to the cart + /** + * Add custom key-value properties to the cart for storing metadata, tracking information, or integration data. Properties are merged with existing cart properties. + * * @param properties the custom key to value object to attribute to the cart */ addCartProperties(properties: Record): Promise; - /** Removes the specified cart properties + /** + * Remove specific cart properties by their keys. Only the specified property keys will be removed while other properties remain intact. + * * @param keys the collection of keys to be removed from the cart properties */ removeCartProperties(keys: string[]): Promise; - /** Adds custom properties to the specified line item + /** + * Add custom properties to a specific line item using its [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier). Properties are merged with existing line item properties for metadata storage and tracking. + * * @param uuid the uuid of the line item to which the properties should be stringd * @param properties the custom key to value object to attribute to the line item */ @@ -108,20 +138,26 @@ export interface CartApiContent { properties: Record, ): Promise; - /** Adds custom properties to multiple line items at the same time. + /** + * Add properties to multiple line items simultaneously using an array of inputs containing line item [UUIDs](https://en.wikipedia.org/wiki/Universally_unique_identifier) and their respective properties for efficient bulk operations. + * * @param lineItemProperties the collection of custom line item properties to apply to their respective line items. */ bulkAddLineItemProperties( lineItemProperties: SetLineItemPropertiesInput[], ): Promise; - /** Removes the specified line item properties + /** + * Remove specific properties from a line item by `UUID` and property keys. Only the specified keys will be removed while other properties remain intact. + * * @param uuid the uuid of the line item to which the properties should be removed * @param keys the collection of keys to be removed from the line item properties */ removeLineItemProperties(uuid: string, keys: string[]): Promise; - /** Add a discount on a line item to the cart + /** + * Apply a discount to a specific line item using its [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier). Specify the discount type (`'Percentage'` or `'FixedAmount'`), title, and amount value. + * * @param uuid the uuid of the line item that should receive a discount * @param type the type of discount applied (example: 'Percentage') * @param title the title attributed with the discount @@ -134,19 +170,25 @@ export interface CartApiContent { amount: string, ): Promise; - /** Set line item discounts to multiple line items at the same time. + /** + * Apply discounts to multiple line items simultaneously. Each input specifies the line item `UUID` and discount details for efficient bulk discount operations. + * * @param lineItemDiscounts a map of discounts to add. They key is the uuid of the line item you want to add the discount to. The value is the discount input. */ bulkSetLineItemDiscounts( lineItemDiscounts: SetLineItemDiscountInput[], ): Promise; - /** Sets an attributed staff to all line items in the cart. + /** + * Set the attributed staff member for all line items in the cart using the staff `ID`. Pass `undefined` to clear staff attribution from all line items. + * * @param staffId the ID of the staff. Providing undefined will clear the attributed staff from all line items. */ setAttributedStaff(staffId: number | undefined): Promise; - /** Sets an attributed staff to a specific line items in the cart. + /** + * Set the attributed staff member for a specific line item using the staff `ID` and line item `UUID`. Pass `undefined` as `staffId` to clear attribution from the line item. + * * @param staffId the ID of the staff. Providing undefined will clear the attributed staff on the line item. * @param lineItemUuid the UUID of the line item. */ @@ -155,23 +197,30 @@ export interface CartApiContent { lineItemUuid: string, ): Promise; - /** Remove all discounts from a line item + /** + * Remove all discounts from a specific line item identified by its `UUID`. This will clear any custom discounts applied to the line item while preserving discount allocation history. + * * @param uuid the uuid of the line item whose discounts should be removed */ removeLineItemDiscount(uuid: string): Promise; - /** Add an address to the customer (Customer must be present) + /** + * Add a new address to the customer associated with the cart. The customer must be present in the cart before adding addresses. + * * @param address the address object to add to the customer in cart */ addAddress(address: Address): Promise; /** - * Delete an address from the customer (Customer must be present) + * Delete an existing address from the customer using the address `ID`. The customer must be present in the cart to perform this operation. + * * @param addressId the address ID to delete */ deleteAddress(addressId: number): Promise; - /** Update the default address for the customer (Customer must be present) + /** + * Set a specific address as the default address for the customer using the address `ID`. The customer must be present in the cart to update the default address. + * * @param addressId the address ID to set as the default address */ updateDefaultAddress(addressId: number): Promise; diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/api/connectivity-api/connectivity-api.ts b/packages/ui-extensions/src/surfaces/point-of-sale/api/connectivity-api/connectivity-api.ts index af3329a9c5..ee9ce44204 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/api/connectivity-api/connectivity-api.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/api/connectivity-api/connectivity-api.ts @@ -2,23 +2,29 @@ import type {RemoteSubscribable} from '@remote-ui/async-subscription'; export type ConnectivityStateSeverity = 'Connected' | 'Disconnected'; +/** + * Represents the current Internet connectivity status of the device. Indicates whether the device has an active Internet connection or is offline. + */ export interface ConnectivityState { /** - * Whether the device is connected to the internet + * Whether the device is connected to the Internet. Returns `'Connected'` when the device has an active Internet connection and can communicate with remote servers, or `'Disconnected'` when the device is offline and can't reach the Internet. + * + * This state reflects the actual network connectivity, not just WiFi/cellular availability—a device can be connected to WiFi but still show `'Disconnected'` if that network has no Internet access. + * + * Commonly used for implementing offline-aware functionality (queuing operations, showing cached data), displaying connectivity indicators in the UI, disabling network-dependent features when offline, or providing user feedback about connection status. */ internetConnected: ConnectivityStateSeverity; } export interface ConnectivityApiContent { /** - * Creates a subscription to changes in connectivity. - * Provides an initial value and a callback to subscribe to value changes. + * Creates a subscription to changes in connectivity. Provides an initial value and a callback to subscribe to value changes. Use for implementing offline-aware functionality and reactive connectivity handling. */ subscribable: RemoteSubscribable; } /** - * Access information about the device connectivity + * The `ConnectivityApi` object provides access to current connectivity information and change notifications. Access these properties through `api.connectivity` to monitor network status. */ export interface ConnectivityApi { connectivity: ConnectivityApiContent; diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/api/customer-api/customer-api.ts b/packages/ui-extensions/src/surfaces/point-of-sale/api/customer-api/customer-api.ts index cf7f811aa9..45ab2f03b2 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/api/customer-api/customer-api.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/api/customer-api/customer-api.ts @@ -1,10 +1,13 @@ +/** + * The `CustomerApi` object provides access to customer data in customer-specific extension contexts. Access this property through `api.customer` to retrieve information about the customer currently being viewed or interacted with in the POS interface. + */ export interface CustomerApi { customer: CustomerApiContent; } export interface CustomerApiContent { /** - * The unique identifier for the customer + * The unique identifier for the customer. Use for customer lookups, applying customer-specific pricing, enabling personalized features, and integrating with external systems. */ id: number; } diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/api/device-api/device-api.ts b/packages/ui-extensions/src/surfaces/point-of-sale/api/device-api/device-api.ts index ce49af2a2a..945ca75340 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/api/device-api/device-api.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/api/device-api/device-api.ts @@ -1,20 +1,20 @@ export interface DeviceApiContent { /** - * The name of the device + * The name of the device as configured by the merchant or system. Use for displaying device information in interfaces, logging, or support contexts where device identification is helpful. */ name: string; /** - * The string ID of the device + * Retrieves the unique string identifier for the device. Returns a promise that resolves to the device ID. Use for device-specific data storage, analytics tracking, or implementing device-based permissions and configurations. */ getDeviceId(): Promise; /** - * Whether the device is a tablet + * Determines whether the device is a tablet form factor. Returns a promise that resolves to `true` for tablets, `false` for other device types. Use for implementing responsive design, optimizing touch targets, or providing device-appropriate user experiences. */ isTablet(): Promise; } /** - * Access information about the device, like name and ID + * 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. */ export interface DeviceApi { device: DeviceApiContent; diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/api/draft-order-api/draft-order-api.ts b/packages/ui-extensions/src/surfaces/point-of-sale/api/draft-order-api/draft-order-api.ts index 83f2d88339..2783f5e0d2 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/api/draft-order-api/draft-order-api.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/api/draft-order-api/draft-order-api.ts @@ -1,20 +1,23 @@ +/** + * The `DraftOrderApi` object provides access to draft order data in draft order-specific extension contexts. Access this property through `api.draftOrder` to retrieve information about the draft order currently being viewed or interacted with in the POS interface. + */ export interface DraftOrderApi { draftOrder: DraftOrderApiContent; } export interface DraftOrderApiContent { /** - * The unique identifier for the draft order + * The unique identifier for the draft order. Use for draft order lookups, implementing order-specific functionality, and integrating with external systems. */ id: number; /** - * The name of the draft order + * The name of the draft order as configured by the merchant. Use for draft order identification, displays, and customer-facing interfaces. */ name: string; /** - * The unique identifier of the customer associated with the draft order + * The unique identifier of the customer associated with the draft order. Returns `undefined` if no customer is associated. Use for customer-specific functionality and personalized experiences. */ customerId?: number; } diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/api/locale-api/locale-api.ts b/packages/ui-extensions/src/surfaces/point-of-sale/api/locale-api/locale-api.ts index ad9916c70d..08e79cdb02 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/api/locale-api/locale-api.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/api/locale-api/locale-api.ts @@ -1,15 +1,14 @@ import type {RemoteSubscribable} from '@remote-ui/async-subscription'; export interface LocaleApiContent { - /** IETF-formatted locale at time of page load and a callback to subscribe to value changes. Current supports only one subscription. - * You can utilize `makeStatefulSubscribable` on a `RemoteSubscribable` to implement multiple subscriptions. - * Using `makeStatefulSubscribable` or the corresponding hooks counts as a subscription. + /** + * Provides the current IETF-formatted locale (for example, "en-US") and allows you to subscribe to locale changes. Supports only one subscription at a time. To enable multiple subscriptions, use `makeStatefulSubscribable` on the `RemoteSubscribable` object. Using `makeStatefulSubscribable` or related hooks counts as an active subscription. */ subscribable: RemoteSubscribable; } /** - * Access the merchant’s current locale (in [IETF format](https://en.wikipedia.org/wiki/IETF_language_tag)) to internationalize your extension content. + * The `LocaleApi` object provides access to current locale information and change notifications. Access these properties through `api.locale` to retrieve and monitor locale data. */ export interface LocaleApi { locale: LocaleApiContent; diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/api/navigation-api/navigation-api.ts b/packages/ui-extensions/src/surfaces/point-of-sale/api/navigation-api/navigation-api.ts index 53b22de5d1..0b449e797e 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/api/navigation-api/navigation-api.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/api/navigation-api/navigation-api.ts @@ -1,20 +1,22 @@ export interface NavigationApiContent { - /** Navigate to a route in current navigation tree. - * Pushes the specified screen if it isn't present in the navigation tree, goes back to a created screen otherwise. - * @param screenName the name of the screen you want to navigate to. - * @param params the parameters you want to pass to that screen. + /** + * Navigate to a route in current navigation tree. Pushes the specified screen if it isn't present in the navigation tree, goes back to a created screen otherwise. Use for implementing multi-screen workflows with parameter passing between screens. */ navigate(screenName: string, params?: any): void; - /** Pops the currently shown screen */ + /** + * Pops the currently shown screen from the navigation stack. Use for implementing back navigation, returning to previous screens, or programmatically navigating backward in multi-screen workflows. + */ pop(): void; - /** Dismisses the extension. */ + /** + * Dismisses the extension modal completely. Use for closing the modal when workflows are complete, cancelled, or when users need to return to the main POS interface. + */ dismiss(): void; } /** - * Access the navigation API for navigation functionality from a full screen modal. + * The `NavigationApi` object provides screen-based navigation functionality for modal interfaces. Access these methods through `api.navigation` to manage screen navigation and modal dismissal. */ export interface NavigationApi { navigation: NavigationApiContent; diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/api/order-api/order-api.tsx b/packages/ui-extensions/src/surfaces/point-of-sale/api/order-api/order-api.tsx index 8cbd6af9e5..00ec7002e1 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/api/order-api/order-api.tsx +++ b/packages/ui-extensions/src/surfaces/point-of-sale/api/order-api/order-api.tsx @@ -1,26 +1,23 @@ /** - * Interface to access the order + * The `OrderApi` object provides access to order data in order-specific extension contexts. Access this property through `api.order` to retrieve information about the order currently being viewed or interacted with in the POS interface. */ export interface OrderApi { order: OrderApiContent; } -/** - * Interface for Order details - */ export interface OrderApiContent { /** - * The unique identifier for the order + * The unique identifier for the order. Use for order lookups, implementing order-specific functionality, and integrating with external systems. */ id: number; /** - * The name of the order + * The name of the order as configured by the merchant. Use for order identification, displays, and customer-facing interfaces. */ name: string; /** - * The unique identifier of the customer associated with the order + * The unique identifier of the customer associated with the order. Returns `undefined` if no customer is associated. Use for customer-specific functionality and personalized experiences. */ customerId?: number; } diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/api/product-api/product-api.ts b/packages/ui-extensions/src/surfaces/point-of-sale/api/product-api/product-api.ts index 143c1e4f05..dbb53b9c31 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/api/product-api/product-api.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/api/product-api/product-api.ts @@ -1,10 +1,17 @@ +/** + * The `ProductApi` object provides access to product and variant data in product-specific extension contexts. Access this property through `api.product` to retrieve information about the product or variant currently being viewed or interacted with in the POS interface. + */ export interface ProductApi { product: ProductApiContent; } export interface ProductApiContent { /** - * The unique identifier for the product. + * The unique identifier for the product. Use for product lookups, implementing product-specific functionality, and integrating with external systems. */ id: number; + /** + * The unique identifier for the product variant. Use for variant-specific operations, cart additions, and inventory management. + */ + variantId: number; } diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/api/product-search-api/product-search-api.ts b/packages/ui-extensions/src/surfaces/point-of-sale/api/product-search-api/product-search-api.ts index 28c70e9807..bde49109ba 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/api/product-search-api/product-search-api.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/api/product-search-api/product-search-api.ts @@ -9,75 +9,94 @@ export type ProductSortType = | 'ALPHABETICAL_Z_TO_A'; /** - * Base interface for pagination. + * Specifies parameters for cursor-based pagination. Includes the cursor position and the number of results to retrieve per page. */ export interface PaginationParams { /** - * Specifies the number of results to be returned in this page. The maximum number of items that will be returned is 50. + * Specifies the number of results to be returned in this page. The maximum number of items that will be returned is 50. Use to control page size based on your UI requirements and performance considerations. */ first?: number; /** - * Specifies the page cursor. Items after this cursor will be returned. + * Specifies the page cursor. Items after this cursor will be returned in the next page. Use the cursor from previous search results to implement pagination and load additional products as users navigate through search results. */ afterCursor?: string; } /** - * Interface for product search + * Specifies the parameters for searching products. Includes query text, pagination options, and sorting preferences for product search operations. */ export interface ProductSearchParams extends PaginationParams { /** - * The search term to be used to search for POS products. + * The search term used to find products by name, description, or other searchable fields. When provided, results are automatically sorted by relevance to the query, overriding any `sortType` setting. Use for implementing text-based product search functionality. */ queryString?: string; /** - * Specifies the order in which products should be sorted. When a `queryString` is provided, sortType will not have any effect, as the results will be returned in order by relevance to the `queryString`. + * Specifies the order in which products should be sorted. When a `queryString` is provided, sortType will not have any effect, as the results will be returned in order by relevance to the `queryString`. Available options: + * + * - **`RECENTLY_ADDED`** - Sorts products by creation date in descending order, displaying the most recently added products first. Use to highlight new inventory additions or showcase latest product arrivals. + * - **`RECENTLY_ADDED_ASCENDING`** - Sorts products by creation date in ascending order, displaying the oldest products first. Use when prioritizing established products or implementing chronological browsing from earliest to newest. + * - **`ALPHABETICAL_A_TO_Z`** - Sorts products alphabetically by title from A to Z. Use for product catalogs where alphabetical organization improves browsing efficiency and helps users locate products by name quickly. + * - **`ALPHABETICAL_Z_TO_A`** - Sorts products alphabetically by title from Z to A in reverse order. Use when reverse alphabetical sorting is needed for specialized browsing patterns or user preferences. */ sortType?: ProductSortType; } export interface ProductSearchApiContent { - /** Search for products on the POS device. + /** + * Searches for products on the POS device using text queries and sorting options. Returns paginated results with up to 50 products per page. When a query string is provided, results are sorted by relevance. Use for implementing custom search interfaces, product discovery features, or filtered product listings. + * * @param searchParams The parameters for the product search. */ searchProducts( searchParams: ProductSearchParams, ): Promise>; - /** Fetches a single product's details. + /** + * Retrieves detailed information for a single product by its ID. Returns `undefined` if the product doesn't exist or isn't available on the POS device. Use for displaying product details, validating product availability, or building product-specific workflows. + * * @param productId The ID of the product to lookup. */ fetchProductWithId(productId: number): Promise; - /** Fetches multiple products' details. + /** + * Retrieves detailed information for multiple products by their IDs. Limited to 50 products maximum—additional IDs are automatically removed. Returns results with both found and not found products clearly identified. Use for bulk product lookups, building product collections, or validating product lists. + * * @param productIds Specifies the array of product IDs to lookup. This is limited to 50 products. All excess requested IDs will be removed from the array. */ fetchProductsWithIds( productIds: number[], ): Promise>; - /** Fetches a single product variant's details. + /** + * Retrieves detailed information for a single product variant by its ID. Returns `undefined` if the variant doesn't exist or isn't available. Use for displaying variant-specific details like pricing, inventory, or options when working with specific product configurations. + * * @param productVariantId The ID of the product variant to lookup. */ fetchProductVariantWithId( productVariantId: number, ): Promise; - /** Fetches multiple product variants' details. + /** + * Retrieves detailed information for multiple product variants by their IDs. Limited to 50 variants maximum—additional IDs are automatically removed. Returns results with both found and not found variants clearly identified. Use for bulk variant lookups or building variant-specific collections. + * * @param productVariantIds Specifies the array of product variant IDs to lookup. This is limited to 50 product variants. All excess requested IDs will be removed from the array. */ fetchProductVariantsWithIds( productVariantIds: number[], ): Promise>; - /** Fetches all product variants associated with a product. + /** + * Retrieves all product variants associated with a specific product ID. Returns all variants at once without pagination. Use for displaying complete variant options, building variant selectors, or analyzing all available configurations for a product. + * * @param productId The product ID. All variants' details associated with this product ID are returned. */ fetchProductVariantsWithProductId( productId: number, ): Promise; - /** Fetches a page of product variants associated with a product. + /** + * Retrieves product variants for a specific product with pagination support. Use when a product has many variants and you need to load them incrementally for better performance. Ideal for products with extensive variant collections that would be too large to load at once. + * * @param paginationParams The parameters for pagination. */ fetchPaginatedProductVariantsWithProductId( @@ -87,7 +106,7 @@ export interface ProductSearchApiContent { } /** - * Access Point of Sale's native product search functionality. + * The `ProductSearchApi` object provides methods for searching and retrieving product information. Access these methods through `api.productSearch` to search products and fetch detailed product data. */ export interface ProductSearchApi { productSearch: ProductSearchApiContent; diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/api/scanner-api/scanner-api.ts b/packages/ui-extensions/src/surfaces/point-of-sale/api/scanner-api/scanner-api.ts index c9a55745ba..a9a0951e4d 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/api/scanner-api/scanner-api.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/api/scanner-api/scanner-api.ts @@ -3,28 +3,40 @@ import type {RemoteSubscribable} from '@remote-ui/async-subscription'; /** The scanner source the POS device supports. */ export type ScannerSource = 'camera' | 'external' | 'embedded'; +/** + * Represents the data from a scanner event. Contains the scanned string data and the hardware source that captured the scan. + */ export interface ScannerSubscriptionResult { - /** The string data from the last scanner event received. */ + /** + * The string data from the last scanner event received. Contains the scanned barcode, QR code, or other scannable data. Returns `undefined` when no scan data is available. Use to process scanned content and implement scan-based business logic. + */ data?: string; - /** The scanning source from which the scan event came. */ + /** + * The scanning source from which the scan event came. Returns one of the following scanner types: + * + * - `'camera'` - Device camera for scanning through the camera interface (available on most mobile POS devices) + * - `'external'` - External scanner hardware connected using USB, Bluetooth, or other methods (handheld scanners, dedicated devices) + * - `'embedded'` - Built-in scanning hardware integrated into the POS device (specialized terminals with integrated scanning) + * + * Returns `undefined` when no scan source is available. Use to implement source-specific logic or provide feedback about scanning method. + */ source?: ScannerSource; } export interface ScannerApiContent { - /** Creates a subscription to scan events - * Provides an initial value and a callback to subscribe to value changes. Currently supports only one subscription. - * You can utilize `makeStatefulSubscribable` on a `RemoteSubscribable` to implement multiple subscriptions. - * Using `makeStatefulSubscribable` or the corresponding hooks counts as a subscription. + /** + * Subscribe to scan events to receive barcode and QR code data when scanned. Supports one subscription at a time. Use for receiving real-time scan results. */ scannerDataSubscribable: RemoteSubscribable; - /** Creates a subscription to the scanning sources available on the POS device. - * Provides an initial value and a callback to subscribe to value changes. Currently supports only one subscription. - * You can utilize `makeStatefulSubscribable` on a `RemoteSubscribable` to implement multiple subscriptions. - * Using `makeStatefulSubscribable` or the corresponding hooks counts as a subscription. + /** + * Subscribe to changes in available scanner sources on the device. Supports one subscription at a time. Use to monitor which scanners are available (camera, external, or embedded). */ scannerSourcesSubscribable: RemoteSubscribable; } +/** + * The `ScannerApi` object provides access to scanning functionality and scanner source information. Access these properties through `api.scanner` to monitor scan events and available scanner sources. + */ export interface ScannerApi { scanner: ScannerApiContent; } diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/api/session-api/session-api.ts b/packages/ui-extensions/src/surfaces/point-of-sale/api/session-api/session-api.ts index 24f5e72e5c..a8181e6bbf 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/api/session-api/session-api.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/api/session-api/session-api.ts @@ -2,18 +2,17 @@ import type {Session} from '../types/session'; export interface SessionApiContent { /** - * Access information on the current POS session. + * Provides comprehensive information about the current POS session including shop details, user authentication, location data, staff member information, currency settings, and POS version. This data is static for the duration of the session and updates when users switch locations or staff members change. */ currentSession: Session; /** - * Get a fresh session token for communication with your app's backend service. - * Calls to Shopify APIs must be made by your app’s backend service. + * Generates a fresh session token for secure communication with your app's backend service. Returns `undefined` when the authenticated user lacks proper app permissions. The token is a Shopify [OpenID Connect](https://en.wikipedia.org/wiki/OpenID#OpenID_Connect_(OIDC)) ID Token that should be used in `Authorization` headers for backend API calls. This is based on the authenticated user, not the pinned staff member. */ getSessionToken: () => Promise; } /** - * Access information on the current Session, including data on the current shop, user, staff and location. + * The `SessionApi` object provides access to current session information and authentication methods. Access these properties and methods through `api.session` to retrieve shop data and generate secure tokens. These methods enable secure API calls while maintaining user privacy and [app permissions](https://help.api.com/manual/your-account/users/roles/permissions/store-permissions#apps-and-channels-permissions). */ export interface SessionApi { session: SessionApiContent; diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/api/toast-api/toast-api.ts b/packages/ui-extensions/src/surfaces/point-of-sale/api/toast-api/toast-api.ts index 160d8651a8..ae22634d75 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/api/toast-api/toast-api.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/api/toast-api/toast-api.ts @@ -1,16 +1,28 @@ +/** + * Specifies configuration options for displaying toast notifications. Controls the duration and display behavior of temporary notification messages. + */ export interface ShowToastOptions { + /** + * The duration in milliseconds that the toast message remains visible before automatically dismissing. If not specified, the toast uses the default system duration (typically 3-5 seconds depending on the platform). + * + * Shorter durations (1000-2000ms) work well for simple confirmations like "Item added" or "Saved". Longer durations (5000-7000ms) provide adequate reading time for important messages or multi-sentence notifications. Very short durations (< 1000ms) may not give users enough time to read the message. The toast dismisses automatically after the specified duration, but users may also manually dismiss it if the system supports swipe-to-dismiss gestures. + */ duration?: number; } export interface ToastApiContent { /** - * Show a toast. + * Displays a toast notification with the specified text content. The message appears as a temporary overlay that automatically dismisses after the specified duration. Use for providing immediate user feedback, confirming actions, or communicating status updates without interrupting the user's workflow. + * * @param content The text content to display. * @param options An object containing ShowToastOptions. */ show: (content: string, options?: ShowToastOptions) => void; } +/** + * The `ToastApi` object provides methods for displaying temporary notification messages. Access these methods through `api.toast` to show user feedback and status updates. + */ export interface ToastApi { toast: ToastApiContent; } diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/api/types/cart.ts b/packages/ui-extensions/src/surfaces/point-of-sale/api/types/cart.ts index e2f0f527e6..b514a5e95f 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/api/types/cart.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/api/types/cart.ts @@ -1,108 +1,267 @@ import {CountryCode} from './country-code'; +/** + * Represents the shopping cart state, including line items, pricing, customer information, and applied discounts. Provides comprehensive access to all cart data and operations. + */ export interface Cart { + /** + * The subtotal amount of the cart before taxes and discounts, formatted as a currency string. + */ subtotal: string; + /** + * The total tax amount for the cart, formatted as a currency string. + */ taxTotal: string; + /** + * The final total amount including all items, taxes, and discounts, formatted as a currency string. + */ grandTotal: string; + /** + * The cart note to set during bulk update. Replaces existing note or sets new note if none exists. Set to `undefined` to remove current note. + */ note?: string; + /** + * The cart-level discount to apply during bulk update. Replaces existing cart discount. Set to `undefined` to remove current discount. + */ cartDiscount?: Discount; + /** + * An array of cart-level discounts to apply during bulk update. Replaces all existing cart discounts with the provided array. + */ cartDiscounts: Discount[]; + /** + * The customer to associate with the cart during bulk update. Replaces existing customer or converts guest cart to customer cart. + */ customer?: Customer; + /** + * An array of line items to set during bulk update. Completely replaces existing cart contents—removes all current items and adds the provided ones. + */ lineItems: LineItem[]; + /** + * The custom key-value properties attached to this line item. Empty object if no properties are set. Commonly used for metadata, customization options, or integration data. + */ properties: Record; } +/** + * Represents basic customer identification information. Contains the customer ID for linking to detailed customer data and enabling customer-specific features. + */ export interface Customer { + /** + * The unique numeric identifier for the customer in Shopify's system. This ID is consistent across all Shopify systems and APIs. Used to link this customer reference to the full customer record with complete profile information. Commonly used for customer lookups, applying customer-specific pricing or discounts, linking orders to customer accounts, or integrating with customer management systems. + */ id: number; + /** + * The customer's email address for communication and account identification. Used for sending order confirmations, receipts, marketing communications, and account recovery. Returns `undefined` when no email is associated with the customer account. + */ email?: string; + /** + * The customer's first name (given name) as stored in their Shopify account. Used for personalizing communications and displaying customer information on receipts and orders. Returns `undefined` when first name isn't provided. + */ firstName?: string; + /** + * The customer's last name (family name/surname) as stored in their Shopify account. Used for personalizing communications and displaying customer information on receipts and orders. Returns `undefined` when last name isn't provided. + */ lastName?: string; + /** + * Internal notes about this customer for merchant reference only. This field is not visible to the customer and can contain information like preferences, special instructions, or account history. Returns `undefined` when no notes have been added. Commonly used for tracking customer preferences, recording important account details, or communicating information between staff members. + */ note?: string; } +/** + * Represents an individual item in the shopping cart. Contains product information, pricing, quantity, discounts, and customization details for a single cart entry. + */ export interface LineItem { + /** + * The unique [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier) string identifier for this specific line item within the cart. This identifier is generated when the line item is added to the cart and remains constant for that line item throughout its lifecycle. The UUID distinguishes this line item from other line items in the cart, even if they represent the same product or variant. This is the primary key for line item operations—all Cart API methods that target specific line items require this UUID. Commonly used for updating line item properties, applying line item discounts, removing items from cart, setting selling plans, or tracking individual line items through the checkout process. + */ uuid: string; + /** + * The unit price for a single unit of this custom sale item as a string value. This represents the price per item in the store's currency (for example, `"25.00"` for $25.00, `"99.99"` for $99.99). String format ensures precision for financial calculations. The total line item cost is calculated as this price multiplied by the quantity. Commonly used for pricing the custom sale, calculating line totals, displaying the charge to customers, or generating receipts with itemized pricing. + */ price?: number; + /** + * The number of units of this custom sale item to add to the cart. Must be a positive integer (minimum 1) representing how many of this custom item the customer is purchasing. Since custom sales don't have inventory tracking, any quantity can be entered without stock validation. Commonly used for specifying how many of the custom item to charge for, calculating line totals (price × quantity), or displaying quantity on receipts and invoices. + */ quantity: number; + /** + * The customer-facing display name for this custom sale item. This is the text that will appear on receipts, in the cart, and on order confirmations to describe what was sold. Should be descriptive and clear (for example, "Repair Service", "Custom Engraving", "Consultation Fee", "Special Order Item"). This is required to create a custom sale. Commonly used for cart and receipt displays, order identification, or describing the custom item in customer communications. + */ title?: string; + /** + * The unique numeric identifier for the product variant this bundle component represents. Links to a specific variant in the Shopify catalog. Returns `undefined` for custom components or non-catalog items within the bundle. When present, this ID can be used to fetch full variant details or verify component inventory. Commonly used for component inventory management, linking bundle components to catalog records, or loading component variant details. + */ variantId?: number; + /** + * The unique numeric identifier for the product this bundle component represents. Links to the parent product in the Shopify catalog. Returns `undefined` for custom components or non-catalog items within the bundle. When present, this ID can be used to fetch full product information about the component. Commonly used for component product lookups, grouping bundle components, or linking to product records. + */ productId?: number; + /** + * An array of all discounts applied specifically to this line item (not cart-level discounts). Each discount object contains the amount, type, and description. The array is empty when no line item-specific discounts are applied. Multiple discounts can apply to a single line item when discount stacking is enabled. The sum of discount amounts reduces the line item's contribution to the cart total. Commonly used for displaying line item savings ("You save $5.00"), showing discount breakdowns in itemized views, calculating effective prices after discounts, or implementing discount-aware business logic. + */ discounts: Discount[]; + /** + * Whether this custom sale item is subject to tax calculations. When `true`, taxes are calculated and applied to this item based on location tax rules and settings. When `false`, this item is tax-exempt and no tax is charged. Tax exemption might apply for services, specific product categories, or non-taxable items depending on jurisdiction. Commonly used for determining whether to calculate taxes on this custom sale, compliance with tax regulations, displaying tax-inclusive vs tax-exclusive pricing, or generating accurate tax reports. + */ taxable: boolean; + /** + * The Stock Keeping Unit (SKU) identifier for this line item as configured in the product catalog. SKUs are merchant-defined alphanumeric codes used for inventory tracking, fulfillment, and product identification (for example, "TSHIRT-BLU-LG", "12345-A"). Returns `undefined` when no SKU is configured for the product variant, which is common for products without inventory tracking or custom sales. The SKU is unique within the merchant's catalog and is often used with barcode scanners or inventory management systems. Commonly used for inventory tracking, displaying product codes on receipts, integrating with warehouse management systems, or matching products with external SKU-based systems. + */ sku?: string; + /** + * The vendor or brand name for this line item as configured in the product catalog (for example, "Nike", "Acme Corp", "House Brand"). This indicates who manufactures or supplies the product. Returns `undefined` when no vendor is set for the product, which is common for products where vendor tracking isn't used. Vendors are merchant-defined and not standardized. Commonly used for vendor-specific displays in cart or receipts, filtering or grouping products by vendor, implementing vendor-based business logic (special handling for certain suppliers), or reporting sales by vendor. + */ vendor?: string; + /** + * The custom key-value properties attached to this line item. Empty object if no properties are set. Commonly used for metadata, customization options, or integration data. + */ properties: {[key: string]: string}; + /** + * Whether this line item is a gift card product. When `true`, indicates this is a Shopify gift card (digital or physical) which has special handling—gift cards don't affect inventory, have different tax treatment in some jurisdictions, and generate gift card codes upon purchase. When `false`, this is a regular product, custom sale, or other non-gift-card item. Gift card line items may have restrictions on discounts or combinations with other line items. Commonly used for implementing gift card-specific UI, applying gift card business rules, excluding gift cards from certain promotions, or separating gift card sales in reporting. + */ isGiftCard: boolean; } +/** + * Represents a discount applied to a cart or transaction, including amount and description. + */ export interface Discount { + /** + * The discount value to apply. For `'Percentage'` type, this represents the percentage value (For example, "10" for 10% off). For `'FixedAmount'` type, this represents the fixed monetary amount to deduct from the line item price. Commonly used for discount calculations and displaying the discount value to merchants. + */ amount: number; + /** + * A human-readable description of the discount shown to merchants and customers. This typically includes the discount name, promotion details, or discount code (for example, "SUMMER2024", "10% off entire order", "Buy 2 Get 1 Free"). Returns `undefined` when no description is provided. + */ discountDescription?: string; + /** + * The [discount type](https://help.api.com/en/manual/discounts/discount-types) applied to this line item. Can be either `'Percentage'` for percentage-based discounts or `'FixedAmount'` for fixed monetary amount discounts. This determines how the discount amount is calculated and displayed. + */ type?: string; } /** - * Parameters for adding custom properties to a line item. + * Specifies the parameters for adding custom properties to line items. Properties are key-value pairs used for storing metadata, tracking information, or integration data. */ export interface SetLineItemPropertiesInput { /** - * The uuid belonging to the line item which should receive the custom properties. + * The [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier) of the target line item to which the selling plan should be applied. This must match the `uuid` of an existing line item in the current cart. If the UUID doesn't exist in the cart, the operation will fail. The line item's product must support selling plans—attempting to add a selling plan to a line item whose product doesn't have selling plan groups will result in an error. Commonly used to identify which cart item is being configured with a subscription plan. */ lineItemUuid: string; /** - * The custom properties to apply to the line item. + * The custom key-value properties attached to this line item. Empty object if no properties are set. Commonly used for metadata, customization options, or integration data. */ properties: Record; } /** - * Parameters for adding a line item discount. + * Specifies the parameters for applying discounts to individual line items. Includes the discount type, value, and reason for audit and reporting purposes. */ export interface SetLineItemDiscountInput { /** - * The uuid belonging to the line item which should receive the discount. + * The [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier) of the target line item to which the selling plan should be applied. This must match the `uuid` of an existing line item in the current cart. If the UUID doesn't exist in the cart, the operation will fail. The line item's product must support selling plans—attempting to add a selling plan to a line item whose product doesn't have selling plan groups will result in an error. Commonly used to identify which cart item is being configured with a subscription plan. */ lineItemUuid: string; /** - * The discount to be applied to the line item. + * The discount details to apply to the line item. Contains title, type (`'Percentage'` or `'FixedAmount'`), and amount value. */ lineItemDiscount: LineItemDiscount; } +/** + * Represents a discount applied to an individual line item in the cart. + */ export interface LineItemDiscount { /** - * The title of the line item discount. + * The customer-facing display name for this custom sale item. This is the text that will appear on receipts, in the cart, and on order confirmations to describe what was sold. Should be descriptive and clear (for example, "Repair Service", "Custom Engraving", "Consultation Fee", "Special Order Item"). This is required to create a custom sale. Commonly used for cart and receipt displays, order identification, or describing the custom item in customer communications. */ title: string; /** - * The discount type. + * The [discount type](https://help.api.com/en/manual/discounts/discount-types) applied to this line item. Can be either `'Percentage'` for percentage-based discounts or `'FixedAmount'` for fixed monetary amount discounts. This determines how the discount amount is calculated and displayed. */ type: 'Percentage' | 'FixedAmount'; /** - * The percentage or fixed amount for the discount. + * The discount value to apply. For `'Percentage'` type, this represents the percentage value (For example, "10" for 10% off). For `'FixedAmount'` type, this represents the fixed monetary amount to deduct from the line item price. Commonly used for discount calculations and displaying the discount value to merchants. */ amount: string; } +/** + * Represents a custom sale item that isn't linked to a product in the merchant's catalog. Custom sales allow merchants to add arbitrary items to the cart with manually entered details—useful for services, custom orders, one-off items, or products not in the catalog. + */ export interface CustomSale { + /** + * The number of units of this custom sale item to add to the cart. Must be a positive integer (minimum 1) representing how many of this custom item the customer is purchasing. Since custom sales don't have inventory tracking, any quantity can be entered without stock validation. Commonly used for specifying how many of the custom item to charge for, calculating line totals (price × quantity), or displaying quantity on receipts and invoices. + */ quantity: number; + /** + * The customer-facing display name for this custom sale item. This is the text that will appear on receipts, in the cart, and on order confirmations to describe what was sold. Should be descriptive and clear (for example, "Repair Service", "Custom Engraving", "Consultation Fee", "Special Order Item"). This is required to create a custom sale. Commonly used for cart and receipt displays, order identification, or describing the custom item in customer communications. + */ title: string; + /** + * The unit price for a single unit of this custom sale item as a string value. This represents the price per item in the store's currency (for example, `"25.00"` for $25.00, `"99.99"` for $99.99). String format ensures precision for financial calculations. The total line item cost is calculated as this price multiplied by the quantity. Commonly used for pricing the custom sale, calculating line totals, displaying the charge to customers, or generating receipts with itemized pricing. + */ price: string; + /** + * Whether this custom sale item is subject to tax calculations. When `true`, taxes are calculated and applied to this item based on location tax rules and settings. When `false`, this item is tax-exempt and no tax is charged. Tax exemption might apply for services, specific product categories, or non-taxable items depending on jurisdiction. Commonly used for determining whether to calculate taxes on this custom sale, compliance with tax regulations, displaying tax-inclusive vs tax-exclusive pricing, or generating accurate tax reports. + */ taxable: boolean; } +/** + * Represents physical address information for customer shipping and billing. Contains standard address fields including street, city, region, postal code, and country data. + */ export interface Address { + /** + * The primary street address line containing the street number and name (for example, "123 Main Street", "456 Oak Avenue"). This is the first line of the mailing address and is typically required for shipping and billing operations. Returns `undefined` when not provided or not applicable. Commonly used for displaying addresses, calculating shipping rates based on location, validating address completeness, or sending to shipping carriers for label generation. + */ address1?: string; + /** + * The secondary address line for additional location details like apartment number, suite, unit, floor, or building information (for example, "Apt 4B", "Suite 200", "Floor 3"). This field is optional and supplements the primary address line. Returns `undefined` when not provided. Commonly used for complete address display, ensuring deliveries reach the correct destination in multi-unit buildings, or providing detailed shipping instructions. + */ address2?: string; + /** + * The city or locality name for the address (for example, "New York", "Toronto", "London"). Required for most shipping and billing operations as it's needed for calculating shipping zones, determining tax jurisdictions, and routing deliveries. Returns `undefined` when not provided. Commonly used for address display, shipping rate calculations based on destination city, tax determination, or filtering addresses by location. + */ city?: string; + /** + * The company or business name associated with the address (for example, "Acme Corporation", "Smith & Co."). This field is optional and typically used for B2B transactions, business deliveries, or when the shipping/billing address is a commercial location rather than residential. Returns `undefined` for individual/residential addresses. Commonly used for business customer identification, commercial shipping labels, B2B order processing, or company-based address organization. + */ company?: string; + /** + * The first name (given name) of the person associated with this address (for example, "John", "Maria"). Commonly used for personalizing shipping labels, customer communications, and ensuring deliveries reach the correct recipient. Returns `undefined` when not provided. Typically combined with `lastName` for full name display. + */ firstName?: string; + /** + * The last name (family name/surname) of the person associated with this address (for example, "Smith", "Garcia"). Commonly used for complete customer identification, shipping labels, and formal address displays. Returns `undefined` when not provided. Typically combined with `firstName` for full name display (for example, "John Smith"). + */ lastName?: string; + /** + * The contact phone number for this address (for example, "+1-555-123-4567", "(555) 123-4567"). Phone numbers enable carriers to contact recipients for delivery coordination, provide delivery notifications using SMS, or reach customers for address clarification. Format varies by region and may include country codes, area codes, and extensions. Returns `undefined` when not provided. Commonly used for delivery notifications, customer contact during shipping issues, or SMS updates about order status. + */ phone?: string; + /** + * The province, state, or region name for the address (for example, "California", "Ontario", "New South Wales"). Required for calculating regional shipping rates, determining state/provincial taxes, and routing deliveries correctly. The format is the full name rather than abbreviated code. Returns `undefined` when not provided or not applicable (some countries don't have province/state divisions). Commonly used for shipping rate calculations, tax jurisdiction determination, or displaying complete addresses. + */ province?: string; + /** + * The country name for the address in English (for example, "United States", "Canada", "United Kingdom"). Required for international shipping, determining country-specific tax rules, and customs documentation. The full country name is used rather than an abbreviated code. Returns `undefined` when not provided. Commonly used for shipping calculations, tax compliance, customs forms, or country-based address validation. + */ country?: string; + /** + * The postal code or ZIP code for the address (for example, "90210", "M5V 3A8", "SW1A 1AA"). Format varies by country—US uses 5 or 9-digit ZIP codes, Canada uses alphanumeric postal codes, UK uses alphanumeric postcodes. Required for accurate shipping rate calculations, address verification, and location-based services. Returns `undefined` when not provided. Commonly used for shipping rate lookup, address validation, geographic sorting, or carrier integration. + */ zip?: string; + /** + * A customer-defined label or nickname for this address to make it easily identifiable (for example, "Home", "Work", "Main Office", "Warehouse"). This friendly name helps distinguish between multiple saved addresses for the same customer. Returns `undefined` when no custom name is assigned. Commonly used for displaying address selection lists ("Ship to: Home"), organizing customer addresses, or showing address nicknames in dropdowns. + */ name?: string; + /** + * The standardized province or state code (for example, "CA" for California, "ON" for Ontario, "NSW" for New South Wales). This is typically a 2-3 character abbreviation that complements the full `province` name. Codes follow regional standards and enable programmatic province/state matching. Returns `undefined` when not applicable or not provided. Commonly used for precise regional identification in shipping APIs, automated tax calculations, address validation services, or integrating with carriers that require standardized codes. + */ provinceCode?: string; + /** + * The standardized [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code (for example, `"US"` for United States, `"CA"` for Canada, `"GB"` for United Kingdom). This is a two-letter code that precisely identifies the country in a machine-readable format. Complements the full `country` name and is required by many shipping carriers and tax services. Returns `undefined` when not provided. Commonly used for precise country identification in shipping operations, international tax calculations, address validation, customs documentation, or carrier API integration. + */ countryCode?: CountryCode; } diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/api/types/country-code.ts b/packages/ui-extensions/src/surfaces/point-of-sale/api/types/country-code.ts index 66d11a842e..36ca7a8fe6 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/api/types/country-code.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/api/types/country-code.ts @@ -1,5 +1,8 @@ /* eslint @shopify/typescript/prefer-pascal-case-enums: off */ +/** + * The two-letter [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country codes representing all countries and territories. These standard codes are used for addresses, shipping destinations, tax jurisdictions, and regional settings. + */ export enum CountryCode { AF = 'AF', AX = 'AX', diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/api/types/multiple-resource-result.ts b/packages/ui-extensions/src/surfaces/point-of-sale/api/types/multiple-resource-result.ts index 61749a5d0e..56c285958a 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/api/types/multiple-resource-result.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/api/types/multiple-resource-result.ts @@ -1,14 +1,13 @@ /** - * The result of a fetch function where the input is multiple IDs. - * This object contains the resources that were found, as well as an array of IDs specifying which IDs, if any, did not correspond to a resource. + * Represents the result of a bulk resource lookup operation. Contains successfully found resources and identifiers for resources that were not found. */ export interface MultipleResourceResult { /** - * The resources that were fetched using the IDs provided. + * The resources that were fetched using the IDs provided. Contains the successfully found products or variants. Use to access the actual data that was retrieved from the bulk fetch operation. */ fetchedResources: T[]; /** - * The IDs for which a resource was not found. + * The IDs for which a resource was not found. Use to handle missing products or variants gracefully, provide user feedback about unavailable items, or implement fallback logic for missing resources. */ idsForResourcesNotFound: number[]; } diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/api/types/paginated-result.ts b/packages/ui-extensions/src/surfaces/point-of-sale/api/types/paginated-result.ts index f222c7e268..510740eaed 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/api/types/paginated-result.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/api/types/paginated-result.ts @@ -1,20 +1,19 @@ /** - * Contains a page of fetched results. + * Represents the result of a paginated query. Contains the data items, pagination cursors for navigating pages, and information about whether more results exist. */ export interface PaginatedResult { /** - * The items returned from the fetch. + * The items returned from the fetch operation. Contains the actual search results or fetched resources. Use to access the product or variant data returned from search and fetch operations. */ items: T[]; /** - * The cursor of the last item. This can be used to fetch more results. - * The format of this cursor may look different depending on if POS is fetching results from the remote API, or its local database. However, that should not affect its usage with the search functions. + * The cursor of the last item. This can be used to fetch more results. The format of this cursor may look different depending on if POS is fetching results from the remote API, or its local database. However, that should not affect its usage with the search functions. */ lastCursor?: string; /** - * Whether or not there is another page of results that can be fetched. + * Whether there is another page of results that can be fetched. Use to determine whether to show "Load More" buttons, pagination controls, or implement infinite scrolling functionality. */ hasNextPage: boolean; } diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/api/types/product.ts b/packages/ui-extensions/src/surfaces/point-of-sale/api/types/product.ts index 74493566cb..d11bf08f6a 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/api/types/product.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/api/types/product.ts @@ -1,62 +1,226 @@ +/** + * Represents comprehensive product information including metadata, pricing, variants, and availability. Contains all data needed to display and work with products in the POS interface. + */ export interface Product { + /** + * The unique identifier for the product. Use this ID for product-specific operations, API calls, or linking to product details. This ID is consistent across all Shopify systems and can be used for external integrations. + */ id: number; + /** + * The [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp when the product was created. Use for sorting products by creation date, implementing "new product" features, or tracking product catalog growth over time. + */ createdAt: string; + /** + * The [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp when the product was last updated. Use for cache invalidation, tracking recent changes, or implementing "recently updated" product features. + */ updatedAt: string; + /** + * The product's display name as configured by the merchant. Use for product listings, search results, and customer-facing displays. This is the primary product identifier that customers will recognize. + */ title: string; + /** + * The product's plain text description without HTML formatting. Use for displaying product information in contexts where HTML is not supported or when you need clean text content for processing. + */ description: string; + /** + * The product's description with HTML formatting preserved. Use when you need to display rich text content with formatting, links, or other HTML elements in your extension interface. + */ descriptionHtml: string; + /** + * The URL of the product's featured image, if one is set. Returns `undefined` if no featured image is configured. Use for displaying product images in search results, product listings, or detailed product views. + */ featuredImage?: string; + /** + * Whether this product is a gift card. Gift cards have special handling requirements and different business logic. Use to implement gift card-specific workflows, validation, or display special gift card interfaces. + */ isGiftCard: boolean; + /** + * Whether inventory tracking is enabled for this product. When `false`, inventory quantities may not be accurate or meaningful. Use to determine whether to display inventory information or implement inventory-based business logic. + */ tracksInventory: boolean; + /** + * The product's vendor or brand name as configured by the merchant. Use for filtering products by brand, displaying vendor information, or organizing products by supplier. + */ vendor: string; + /** + * The lowest price among all product variants, formatted as a string. Use for displaying price ranges, implementing price-based filtering, or showing starting prices in product listings. + */ minVariantPrice: string; + /** + * The highest price among all product variants, formatted as a string. Use for displaying price ranges, implementing price-based filtering, or showing complete pricing information for products with multiple variants. + */ maxVariantPrice: string; + /** + * The product type category as defined by the merchant (For example, "T-Shirt," "Electronics," "Books"). Use for product categorization, filtering, or implementing category-specific business logic. + */ productType: string; + /** + * The standardized product category classification. Use for product categorization, implementing category-specific business logic, or organizing products by standardized categories. + */ productCategory: string; + /** + * An array of tags associated with the product for categorization and organization. Use for product filtering, search enhancement, or implementing tag-based business logic and promotions. + */ tags: string[]; + /** + * The total number of variants available for this product. Use to determine whether to show variant selection interfaces, implement variant-specific logic, or optimize variant loading strategies. + */ numVariants: number; + /** + * The total available inventory across all variants and locations, if tracking is enabled. Returns `undefined` when inventory tracking is disabled. Use for availability checks, stock level displays, or implementing low-stock alerts. + */ totalAvailableInventory?: number; + /** + * The total inventory count across all variants and locations for this product. Use for inventory management, stock level displays, or implementing low-stock warnings and alerts. + */ totalInventory: number; + /** + * An array of all product variants associated with this product. Each variant contains detailed information including pricing, inventory, and options. Use for building variant selectors, displaying inventory information, or implementing variant-specific functionality. + */ variants: ProductVariant[]; + /** + * An array of product options that define available variant configurations. For example, size and color. Each option includes available values. Use for building variant selection interfaces or understanding product configuration possibilities. + */ options: ProductOption[]; + /** + * Whether the product has only a default variant (no custom options). When `true`, the product doesn't require variant selection. Use to simplify product interfaces and skip variant selection steps for single-variant products. + */ hasOnlyDefaultVariant: boolean; + /** + * Whether the product has any variants currently in stock. Returns `undefined` when inventory information is not available. Use for stock status displays, availability filtering, or implementing out-of-stock product handling. + */ hasInStockVariants?: boolean; + /** + * The URL of the product on the online store, if available. Returns `undefined` when the product is not published online or the store doesn't have an online presence. Use for linking to online product pages or sharing product information. + */ onlineStoreUrl?: string; } +/** + * Represents a specific variant of a product with its own SKU, price, and inventory. Contains variant-specific attributes including options, availability, and identification data. + */ export interface ProductVariant { + /** + * The unique identifier for the product variant. Use this ID for variant-specific operations, cart additions, or inventory lookups. This ID is consistent across all Shopify systems. + */ id: number; + /** + * The [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp when the product variant was created. Use for sorting variants by creation date, implementing "new product" features, or tracking product catalog changes over time. + */ createdAt: string; + /** + * The [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp when the product variant was last updated. Use for cache invalidation, tracking recent changes, or implementing "recently updated" product features. + */ updatedAt: string; + /** + * The variant's display title, typically showing the option combinations. For example, `"Large / Blue"`. Use for variant selection interfaces, cart displays, or anywhere users need to distinguish between variants. + */ title: string; + /** + * The variant's selling price formatted as a string. Use for price displays, cart calculations, or implementing pricing logic. This represents the current selling price for the variant. + */ price: string; + /** + * The variant's compare-at price (original or MSRP price) formatted as a string, if set. Returns `undefined` when no compare-at price is configured. Use for displaying discounts, sale pricing, or savings calculations. + */ compareAtPrice?: string; + /** + * Whether this variant is subject to tax calculations. Use for tax computation logic, pricing displays, or implementing tax-exempt product handling. + */ taxable: boolean; + /** + * The variant's Stock Keeping Unit (SKU) identifier, if configured. Returns `undefined` when no SKU is set. Use for inventory management, product identification, or integration with external systems that use SKU-based tracking. + */ sku?: string; + /** + * The variant's barcode identifier, if configured. Returns `undefined` when no barcode is set. Use for barcode scanning functionality, inventory tracking, or integration with barcode-based systems. + */ barcode?: string; + /** + * The variant's formatted display name for user interfaces. This may differ from the title and is optimized for display purposes. Use for customer-facing variant names in product listings, cart items, or receipt displays. + */ displayName: string; + /** + * The URL of the variant-specific image, if one is configured. Returns `undefined` when no variant image is set. Use for displaying variant-specific images in selection interfaces or product galleries. + */ image?: string; + /** + * Whether inventory tracking is enabled for this specific variant. When `false`, inventory quantities may not be accurate. Use to determine whether to display inventory information or implement inventory-based business logic for this variant. + */ inventoryIsTracked: boolean; + /** + * The inventory quantity available at the current POS location, if inventory tracking is enabled. Returns `undefined` when inventory tracking is disabled. Use for location-specific inventory displays, stock availability checks, or local inventory management. + */ inventoryAtLocation?: number; + /** + * The total inventory quantity across all locations for this variant, if available. Returns `undefined` when this information is not available. Use for comprehensive inventory views, transfer planning, or multi-location inventory management. + */ inventoryAtAllLocations?: number; + /** + * The inventory policy for this variant, either "DENY" (prevent sales when out of stock) or "CONTINUE" (allow sales when out of stock). Use to implement inventory validation logic and determine whether to allow purchases of out-of-stock items. + */ inventoryPolicy: ProductVariantInventoryPolicy; + /** + * Whether this variant currently has inventory in stock. Returns `undefined` when inventory information is not available. Use for stock status displays, availability checks, or filtering in-stock variants. + */ hasInStockVariants?: boolean; + /** + * An array of option name-value pairs that define this variant's configuration. For example, `[{name: "Size," value: "Large"}, {name: "Color," value: "Blue"}]`. Returns `undefined` for products with only default variants. Use for displaying variant options, building variant selectors, or implementing variant-based logic. + */ options?: ProductVariantOption[]; + /** + * Reference to the parent Product object that this variant belongs to. Returns `undefined` in some contexts to avoid circular references. Use when you need access to product-level information from a variant context. + */ product?: Product; + /** + * The ID of the parent product that this variant belongs to. Use for linking variants back to their parent product, implementing product-level operations, or organizing variants by product. + */ productId: number; + /** + * The variant's position order within the product's variant list. Use for maintaining consistent variant ordering in selection interfaces or implementing custom variant sorting logic. + */ position: number; } +/** + * Represents a single option selection for a product variant, showing one chosen value from a product's configuration options. For example, if a product has Size and Color options, a variant might have one option for Size=Large and another for Color=Blue. + */ export interface ProductVariantOption { + /** + * The option category name (for example, `"Size"`, `"Color"`, `"Material"`, `"Style"`, `"Flavor"`). This is the attribute or dimension along which the product varies. Each product can have up to 3 option names, and each option name can have multiple values. The name is visible to customers in variant selection interfaces. Commonly used for displaying option labels in variant selectors ("Select Size:", "Choose Color:"), building dynamic product configuration UI, or organizing product variations by attribute type. + */ name: string; + /** + * The selected value for this option that defines this specific variant (for example, `"Large"`, `"Blue"`, `"Cotton"`, `"V-Neck"`). This is the specific choice from the available option values that characterizes this variant. For example, if `name` is "Size", the `value` might be "Large" or "Small". Values are set at the variant level—each variant has a unique combination of option values. Commonly used for displaying the variant's configuration ("Size: Large, Color: Blue"), building variant selection dropdowns, or matching user selections to variants. + */ value: string; } +/** + * The inventory policy determining whether sales can continue when a variant has no inventory available: + * - `'DENY'`: Sales are prevented when inventory reaches zero. Customers can't purchase out-of-stock variants. The "Add to cart" action is disabled or shows "Out of stock". This is the default and recommended policy for most physical products to prevent overselling. + * - `'CONTINUE'`: Sales are allowed even when inventory is zero or negative. Customers can purchase out-of-stock variants, creating backorders. This enables pre-orders, made-to-order products, or drop-shipped items where inventory tracking is less critical. + */ export type ProductVariantInventoryPolicy = 'DENY' | 'CONTINUE'; +/** + * Represents a product option definition showing one of the configurable attributes for a product (like Size, Color, Material) along with all the possible values customers can choose from. Products can have up to 3 options. + */ export interface ProductOption { + /** + * The unique numeric identifier for this product option configuration. This ID identifies the option definition itself (not a specific option value or variant). Commonly used for option-specific operations, tracking option configurations, or linking options in external systems. + */ id: number; + /** + * The option category name (for example, `"Size"`, `"Color"`, `"Material"`, `"Style"`, `"Flavor"`). This is the attribute or dimension along which the product varies. Each product can have up to 3 option names, and each option name can have multiple values. The name is visible to customers in variant selection interfaces. Commonly used for displaying option labels in variant selectors ("Select Size:", "Choose Color:"), building dynamic product configuration UI, or organizing product variations by attribute type. + */ name: string; + /** + * An array of all available values for this option that customers can choose from (for example, `["Small", "Medium", "Large", "X-Large"]` for a Size option, or `["Red", "Blue", "Green", "Black"]` for a Color option). The order of values in this array typically represents the display order in variant selectors. Each combination of option values across all options creates a unique variant. For example, a product with Size: [Small, Large] and Color: [Red, Blue] would have 4 variants (Small/Red, Small/Blue, Large/Red, Large/Blue). Commonly used for building variant selection dropdowns, radio buttons, or swatches, validating user selections, or displaying all available choices for an attribute. + */ optionValues: string[]; + /** + * The unique numeric identifier of the parent product to which this option belongs. This links the option definition back to the product it configures. Commonly used for linking options to their parent product, organizing options by product, or implementing product-level option management. + */ productId: number; } diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/api/types/session.ts b/packages/ui-extensions/src/surfaces/point-of-sale/api/types/session.ts index 392276113f..d5d5e08e8a 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/api/types/session.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/api/types/session.ts @@ -1,27 +1,29 @@ +/** + * Defines information about the current POS session. Contains authentication details, location context, and configuration settings that remain constant for the duration of the session. + */ export interface Session { /** - * The shop ID associated with the shop currently logged into POS. + * The unique numeric identifier for the Shopify shop currently logged into POS. This ID is consistent across all Shopify systems and APIs. Commonly used for shop-specific data queries, API authentication, or multi-shop configurations. */ shopId: number; /** - * The user ID associated with the Shopify account currently authenticated on POS. + * The unique numeric identifier for the Shopify account currently authenticated on POS. This represents the logged-in user's account, which may be the shop owner, an admin, or a staff member with POS access. This ID can differ from `staffMemberId` when a different staff member is pinned in for the transaction. Commonly used for user-specific permissions, audit trails, or tracking who performed actions. */ userId: number; /** - * The shop domain associated with the shop currently logged into POS. + * The shop's `.myapi.com` domain name (for example, `"my-store.myapi.com"`). This is the shop's permanent Shopify domain, not custom domains. Commonly used for constructing API URLs, identifying the shop in external systems, or building shop-specific links. */ shopDomain: string; /** - * The location ID associated with the POS' current location. + * The unique numeric identifier for the physical retail location where this POS device is currently operating. Locations represent distinct retail sites, warehouses, or pop-up shops within a merchant's business. This determines which inventory is available, which staff can access the POS, and which location appears on receipts and orders. Commonly used for location-specific inventory queries, sales reports, or implementing location-based features. */ locationId: number; /** - * The staff ID who is currently pinned into the POS. - * Note that this staff member ID may be different to the User ID, as the staff member who enters their PIN may be different to the User who logged onto POS. + * The unique numeric identifier for the staff member currently pinned into the POS session. This represents who is actively using the POS for transactions, which may differ from `userId` when a manager is logged in but a different staff member is pinned for sales attribution. Returns `undefined` when no staff member is pinned. Commonly used for sales attribution, commission tracking, or staff-specific workflows. */ staffMemberId?: number; } diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/ActionItem/ActionItem.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/ActionItem/ActionItem.ts index c569b710fe..2d2edd4ff3 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/ActionItem/ActionItem.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/ActionItem/ActionItem.ts @@ -1,10 +1,11 @@ import {createRemoteComponent} from '@remote-ui/core'; /** - * Renders an `ActionItem` on action targets. Note that the text displayed on this `ActionItem` - * is dependent on the description of the extension. - * @property `enabled` sets whether or not the `ActionItem` can be tapped. - * @property `onPress` the callback that is executed when the user taps the `ActionItem`. + * @deprecated ActionItem has been deprecated. Please use the [Button Component](/docs/api/pos-ui-extensions/components/) instead. + * + * Renders an interactive button component as an entry point for action menu item and block extensions. The text displayed on the ActionItem is determined by the extension's description in your configuration file. Use ActionItem to create tappable surfaces that trigger extension workflows or present modal interfaces. + * + * Note: ActionItem is deprecated in favor of the more flexible Button component which provides additional styling options and better consistency across POS interfaces. */ export interface ActionItemProps { /** diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/Badge/Badge.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/Badge/Badge.ts index c71912c0d3..8aa828ba98 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/Badge/Badge.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/Badge/Badge.ts @@ -8,26 +8,28 @@ export type BadgeVariant = | 'highlight'; export type BadgeStatus = 'empty' | 'partial' | 'complete'; - -/** - * @property text - The text displayed inside the badge. - * @property variant - The appearance and function of the badge. - * @property status - A circle icon displaying the status of the badge. - * @deprecated status - No longer supported as of POS 10.0.0. - */ export interface BadgeProps { /** - * The text displayed inside the badge. + * The text content displayed within the badge. Keep this concise and descriptive to clearly communicate status or category information. Examples include "Paid," "Pending," "Out of Stock," or "VIP Customer." */ text: string; /** - * The appearance and function of the badge. + * Controls the visual styling and semantic meaning of the badge. Available options: + * - `'neutral'` - Gray styling for general status information that doesn't require emphasis. Use for general status updates and standard information. + * - `'critical'` - Red styling for errors, failures, and urgent issues requiring immediate action. Use for urgent issues that need immediate merchant attention. + * - `'warning'` - Orange styling for important notices that require merchant awareness. Use for situations that need attention but aren't critical. + * - `'success'` - Green styling for positive states, completed actions, and successful operations. Use for positive outcomes and successful processes. + * - `'highlight'` - Bright styling for featured content, promotions, or emphasized information. Use for featured content that should stand out. */ variant: BadgeVariant; /** - * A circle icon displaying the status of the badge. + * Displays a circular status indicator alongside the badge text. Available options: + * - `'empty'` - Shows an empty circle indicator + * - `'partial'` - Shows a partially filled circle indicator + * - `'complete'` - Shows a completely filled circle indicator + * * @deprecated No longer supported as of POS 10.0.0. */ status?: BadgeStatus; diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/Banner/Banner.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/Banner/Banner.ts index cea3ad5824..15fc72d444 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/Banner/Banner.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/Banner/Banner.ts @@ -2,45 +2,44 @@ import {createRemoteComponent} from '@remote-ui/core'; export type BannerVariant = 'confirmation' | 'alert' | 'error' | 'information'; -/** - * @property title - The title text displayed on the banner. - * @property variant - The variant type of the banner. - * @property action - The text for the action button. - * @property onPress - The callback function executed when the banner is pressed. - * @property hideAction - Whether to hide the action button. - * @property visible - The visibility state of the banner. - */ export interface BannerProps { /** - * The title text displayed on the banner. + * The title text displayed prominently on the banner. This should be concise and clearly communicate the main message or purpose of the banner to merchants. */ title: string; /** - * The variant type of the banner. + * Controls the visual styling and semantic meaning of the banner. Available options: + * - `'confirmation'` - Green styling for positive outcomes, successful operations, and completed actions + * - `'alert'` - Orange styling for important notices and situations that require merchant attention + * - `'error'` - Red styling for critical errors, failures, and urgent issues requiring immediate action + * - `'information'` - Blue styling for general information, neutral updates, and helpful tips */ variant: BannerVariant; /** - * The text for the action button. + * The text displayed on the action button within the banner. This provides a clear call-to-action for merchants to address the banner's message. Default is `'Dismiss'` if not specified. + * * @defaultValue 'Dismiss' */ action?: string; /** - * The callback function executed when the banner is pressed. + * The callback function executed when the banner or its action button is pressed. Use this to handle user interactions such as dismissing the banner, navigating to relevant screens, or triggering specific actions. Default behavior dismisses the banner if not specified. + * * @defaultValue Callback which dismisses the banner */ onPress?: () => void; /** - * Whether to hide the action button. + * Determines whether the action button is visible on the banner. When set to `true`, the action button is hidden, creating a display-only banner. When `false`, the action button is shown with the specified action text. Default is `true` (action button hidden). + * * @defaultValue true */ hideAction?: boolean; /** - * The visibility state of the banner. + * Controls the visibility state of the banner. When set to `true`, the banner is displayed. When `false`, it's hidden. Use this to programmatically show or hide banners based on application state or user interactions. */ visible: boolean; } diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/Button/Button.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/Button/Button.ts index a675efe5e0..063f7b27b2 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/Button/Button.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/Button/Button.ts @@ -7,35 +7,29 @@ export type ButtonType = /** @deprecated No longer supported as of POS 10.0.0. */ | 'plain'; -/** - * @property `title` the text set on the `Button`. - * @property `type` the type of `Button` to render. Determines the appearance of the button. - * @property `onPress` the callback that is executed when the user taps the button. - * @property `isDisabled` sets whether the `Button` can be tapped. - * @property `isLoading` sets whether the `Button` is displaying an animated loading state. - */ export interface ButtonProps { /** - * The text set on the `Button`. - * - * Note: When using a Button for menu-item targets, the title will be ignored. The text on the menu-item will be the extension's description. + * The text set on the button. When using a button for action (menu item) targets, the title will be ignored. The text on the menu item will be the extension's description. */ title?: string; /** - * The type of `Button` to render. Determines the appearance of the button. - * Note: The 'plain' type is no longer supported as of POS 10.0.0. Using it will default to 'basic'. + * The type of button to render. Determines the appearance of the button. + * - `'primary'` - Creates a prominent call-to-action button with high visual emphasis for the most important action on a screen + * - `'basic'` - Provides a standard button appearance for secondary actions and general interactions + * - `'destructive'` - Displays a warning-styled button for actions that delete, remove, or cause irreversible changes + * - `'plain'` - Deprecated as of POS 10.0.0. Using this option will automatically default to `'basic`' */ type?: ButtonType; /** - * The callback that is executed when the user taps the button. + * The callback that's executed when the user taps the button. */ onPress?: () => void; /** - * Sets whether the `Button` can be tapped. + * Whether the button can be tapped. */ isDisabled?: boolean; /** - * Sets whether the `Button` is displaying an animated loading state. + * Whether the button is displaying an animated loading state. */ isLoading?: boolean; } diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/CameraScanner/CameraScanner.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/CameraScanner/CameraScanner.ts index 3a3d649595..3257ac8c37 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/CameraScanner/CameraScanner.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/CameraScanner/CameraScanner.ts @@ -1,28 +1,26 @@ import {createRemoteComponent} from '@remote-ui/core'; import {BannerVariant} from '../Banner/Banner'; -/** - * @property title - The title of the banner. - * @property variant - The appearance of the banner. - * @property visible - The visibility state of the banner. - */ export interface CameraScannerBannerProps { /** - * The title of the banner. + * The title text displayed on the banner to provide context or instructions to users. */ title: string; /** - * The appearance of the banner. + * The appearance variant of the banner that conveys the type of message being displayed. */ variant: BannerVariant; /** - * The visibility state of the banner. + * Controls the visibility state of the banner within the scanner interface. */ visible: boolean; } export interface CameraScannerProps { + /** + * An optional banner configuration object that displays contextual messages during scanning operations. + */ bannerProps?: CameraScannerBannerProps; } diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/DatePicker/DatePicker.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/DatePicker/DatePicker.ts index 92c75094a7..dfce63f0c8 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/DatePicker/DatePicker.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/DatePicker/DatePicker.ts @@ -1,29 +1,26 @@ import {createRemoteComponent} from '@remote-ui/core'; -/** - * Represents the properties for the DatePicker component. - * @property selected - The selected time. - * @property onChange - A callback for changes. - * @property visibleState - Control the visible state, and a callback to set the visible state as false when the dialog closes. - * @property inputMode - Whether to display the picker in inline (clock) mode or spinner mode. - */ export interface DatePickerProps { /** - * The selected time. - * @defaultValue The current time + * The currently selected date value. Defaults to the current date when not specified. + * + * @defaultValue The current time. */ selected?: string; /** - * A callback for changes. + * A callback function executed when the user selects a date, receiving the selected date string as a parameter. */ onChange?(selected: string): void; /** - * Control the visible state, and a callback to set the visible state as false when the dialog closes. + * A tuple that controls the visible state of the picker and provides a callback to set visibility to false when the dialog closes. The first element is the current visibility state, and the second is a setter function. */ visibleState: [boolean, (visible: boolean) => void]; /** - * Whether to display the picker in inline (calendar) mode or spinner mode. + * The display mode for the date picker. + * - `inline`: A calendar-style interface that displays a full month view where users can tap specific dates. Provides visual context about weekdays, month structure, and date relationships. + * - `spinner`: A spinner-style selector with scrollable columns for month, day, and year. Offers a more compact interface suitable for constrained spaces or when calendar context isn't necessary. + * * @defaultValue 'inline' */ inputMode?: 'inline' | 'spinner'; diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/Dialog/Dialog.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/Dialog/Dialog.ts index d7de98d31f..645bce5318 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/Dialog/Dialog.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/Dialog/Dialog.ts @@ -2,60 +2,53 @@ import {createRemoteComponent} from '@remote-ui/core'; export type DialogType = 'default' | 'alert' | 'error' | 'destructive'; -/** - * @property title - The text displayed in the title of the dialog. - * @property content - The text displayed in the body of the dialog. - * @property actionText - The text displayed in the primary action button of the dialog. - * @property secondaryActionText - The text displayed in the secondary action section of the dialog. - * @property showSecondaryAction - Whether a secondary action displays. - * @property type - Determines the dialog’s appearance and function. - * @property onAction - A callback that performs when the action is triggered. - * @property onSecondaryAction - A callback that is executed when the secondary action is triggered. - * @property isVisible - Whether the dialog should be presented. - */ export interface DialogProps { /** - * The text displayed in the title of the dialog. + * The text displayed in the title of the dialog. This should be concise and clearly communicate the purpose or action being confirmed. */ title: string; /** - * The text displayed in the body of the dialog. + * The text displayed in the body of the dialog. Use this to provide additional context, instructions, or details about the action being confirmed. */ content?: string; /** - * The text displayed in the primary action button of the dialog. + * The text displayed on the primary action button of the dialog. Use clear, action-oriented language like "Delete," "Confirm," "Save," or "Continue." */ actionText: string; /** - * The text displayed in the secondary action section of the dialog. + * The text displayed on the secondary action button, typically used for "Cancel," "Go Back," or alternative actions. Only displayed when `showSecondaryAction` is `true`. */ secondaryActionText?: string; /** - * Whether a secondary action displays. + * Controls whether a secondary action button is displayed alongside the primary action. Set to `true` to show both buttons, `false` to show only the primary action. */ showSecondaryAction?: boolean; /** - * Determines the dialog’s appearance and function. + * Determines the dialog's visual appearance and semantic meaning. Available options: + * - `'default'` - Standard styling for general-purpose dialogs and confirmations + * - `'alert'` - Warning styling for important notices that require attention + * - `'error'` - Error styling for critical issues and failure notifications + * - `'destructive'` - Destructive styling for actions that can't be undone, like deletions */ type?: DialogType; /** - * A callback that performs when the action is triggered. + * The callback function executed when the primary action button is pressed. This should handle the main action the dialog is confirming or requesting. */ onAction: () => void; /** - * A callback that is executed when the secondary action is triggered. + * The callback function executed when the secondary action button is pressed. Typically used to cancel the dialog or provide an alternative action path. */ onSecondaryAction?: () => void; /** - * Whether the dialog should be presented. + * Controls whether the dialog is displayed or hidden. Set to `true` to show the dialog, `false` to hide it. Use this to manage dialog visibility based on user interactions or application state. */ isVisible: boolean; } diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/FormattedTextField/FormattedTextField.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/FormattedTextField/FormattedTextField.ts index 57af4f28dd..ef4aca8ddf 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/FormattedTextField/FormattedTextField.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/FormattedTextField/FormattedTextField.ts @@ -2,22 +2,25 @@ import {createRemoteComponent} from '@remote-ui/core'; import type {AutoCapitalizationType} from '../shared/auto-capitalization-type'; import type {BaseTextFieldProps} from '../shared/BaseTextField'; -/** - * Dictates what type of values can be used in a `TextField`. - */ export type InputType = 'text' | 'number' | 'currency' | 'giftcard' | 'email'; -/** - * @property `inputType` the `InputType` of the `TextField`. This will select the appropriate keyboard. - * @property `autoCapitalize` dictates when the text should be auto-capitalized. - * @property `customValidator` applies a custom validator that can dictate whether or not an entered value is valid. - */ export interface FormattedTextFieldProps extends BaseTextFieldProps { /** - * The `InputType` of the `TextField`. This will select the appropriate keyboard. + * Defines the input type options that determine which specialized keyboard layout is displayed. + * + * - `text`: A general text input type with standard keyboard layout for any text content. + * - `number`: A numeric input type with number-optimized keyboard for entering quantities or numeric values. + * - `currency`: A currency input type with keyboard optimized for monetary amounts and decimal values. + * - `giftcard`: A gift card input type with keyboard optimized for alphanumeric gift card codes. + * - `email`: An email input type with keyboard optimized for email addresses, including easy access to @ and domain symbols. */ inputType?: InputType; /** - * Dictates when the text should be auto-capitalized. + * Defines the auto-capitalization behavior options for text input. + * + * - `none`: No automatic capitalization is applied to the text input. + * - `sentences`: The first letter of each sentence is automatically capitalized. + * - `words`: The first letter of each word is automatically capitalized. + * - `characters`: Every character is automatically capitalized as it is entered. */ autoCapitalize?: AutoCapitalizationType; /** diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/Icon/Icon.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/Icon/Icon.ts index 52ba0bf5ba..ea42bbc426 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/Icon/Icon.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/Icon/Icon.ts @@ -1,5 +1,8 @@ import {createRemoteComponent} from '@remote-ui/core'; +/** + * The name identifier for the icon to display. Choose from the available icon set including commerce operations (`'cart'`, `'products'`, `'orders'`, `'custom-sale'`), payment methods (`'cash'`, `'credit-card'`, `'gift-card'`, `'shopify-payments'`), navigation elements (`'arrow'`, `'chevron-up'`, `'chevron-down'`, `'chevron-left'`, `'chevron-right'`), actions (`'add-customer'`, `'search'`, `'scan-barcode'`, `'refresh'`), status indicators (`'checkmark'`, `'circle-alert'`, `'circle-info'`, `'connectivity-warning'`), and system symbols (`'settings'`, `'help'`, `'menu'`, `'home'`). + */ export type IconName = | 'add-customer' | 'analytics' @@ -83,15 +86,24 @@ export type IconName = | 'delivery' | 'shop-pay'; +/** + * The size of the icon to display. Controls the icon's dimensions and visual prominence in the interface. + * - `'minor'` - Small size for compact spaces, secondary actions, or inline elements + * - `'major'` - Standard size for primary buttons and prominent UI elements (default) + * - `'spot'` - Larger size for featured content, empty states, or emphasis areas + * - `'caption'` - Tiny size for accompanying small text or dense information displays + * - `'badge'` - Minimal size for notification badges, indicators, or status markers + */ export type IconSize = 'minor' | 'major' | 'spot' | 'caption' | 'badge'; export interface IconProps { /** - * A name used to render the icon. + * A name used to render the icon. Choose from the available icon set including commerce-specific symbols like `'cart'`, `'payment'`, `'search'`, navigation arrows, and system indicators. */ name: IconName; /** - * Size of the icon. + * The size of the icon. Use `'minor'` for small icons, `'major'` for standard size (default), `'spot'` for larger emphasis, `'caption'` for tiny text accompaniment, or `'badge'` for small indicators. + * * @defaultValue 'major' */ size?: IconSize; diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/List/List.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/List/List.ts index 029e1c42df..70d3ea94ad 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/List/List.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/List/List.ts @@ -4,38 +4,40 @@ import {ColorType} from '../Text/Text'; export interface ToggleSwitch { /** - * Whether or not the toggle switch is on or off. + * The current state of the toggle switch. When `true`, the switch is in the "on" position. When `false`, it's in the "off" position. */ value?: boolean; /** - * Whether or not the toggle switch is disabled. + * Controls whether the toggle switch can be interacted with. When `true`, the switch is disabled and users cannot change its state. */ disabled?: boolean; } export interface SubtitleType { /** - * The subtitles to display beneath the main label. + * The text content to display as a subtitle beneath the main label. */ content: string; /** - * Property used to modify the subtitle appearance. + * The semantic color of the subtitle text that conveys meaning and intent through visual styling. */ color?: ColorType; } export type ListRowSubtitle = string | SubtitleType; +/** + * Defines the content and styling options for the left side of list rows. + */ export interface ListRowLeftSide { /** - * The main label that will be displayed on the left side of the row. + * The main label text displayed prominently on the left side of the row. */ label: string; /** - * The subtitles to display beneath the main label. Up to 3 subtitles can be displayed. - * Subtitles can optionally be configured with colors by passing an object with a `content` and `color` properties. + * An array of up to three subtitles displayed beneath the main label. Each subtitle can be a string or an object with content and color properties. */ subtitle?: [ListRowSubtitle, ListRowSubtitle?, ListRowSubtitle?]; /** @@ -45,82 +47,94 @@ export interface ListRowLeftSide { */ badge?: BadgeProps; /** - * Colored badges that are displayed underneath the `title` and `subtitles`. + * An array of colored badges displayed underneath the title and subtitles for additional status or category information. */ badges?: BadgeProps[]; + /** + * An image configuration object for displaying images on the far left side of the row with optional badge overlay. + */ image?: { /** - * A link to an image to be displayed on the far left side of the row. + * A URL to an image to be displayed on the far left side of the row. */ source?: string; /** - * A number that is displayed on the top right of the image. + * A numeric badge displayed on the top right corner of the image, typically used for counts or quantities. */ badge?: number; }; } +/** + * Defines the content and interaction options for the right side of list rows. + */ export interface ListRowRightSide { /** - * The main label that will be displayed on the right side of the row. + * An optional label text displayed on the right side of the row for additional information or values. */ label?: string; /** - * Show a chevron. Set this to true if pressing on the row navigates to another screen. + * Controls chevron display. Set to `true` when pressing the row navigates to another screen. + * * @defaultValue `false` */ showChevron?: boolean; /** - * A toggle switch that is be displayed on the right side of the row. + * A toggle switch configuration object displayed on the right side of the row for boolean settings or states. */ toggleSwitch?: ToggleSwitch; } +/** + * Defines the structure and content options for individual rows within the `List` component. + */ export interface ListRow { /** - * The unique identifier for this list item. + * The unique identifier for the list item used for tracking and interaction handling. */ id: string; /** - * The user interface of the left side of the row. + * The content configuration for the left side of the row, including label, subtitles, badges, and optional image. */ leftSide: ListRowLeftSide; /** - * The user interface of the right side of the row. + * The content configuration for the right side of the row, including optional label, chevron, and toggle switch. */ rightSide?: ListRowRightSide; /** - * Callback for when the user taps the row. + * A callback function executed when the user taps the row. */ onPress?: () => void; } export interface ListProps { /** - * A large display title at the top of the `List`. + * A large display title shown at the top of the list. */ title?: string; /** - * A header component for the list. + * A header component displayed at the top of the list for additional context or controls. */ listHeaderComponent?: RemoteFragment; /** - * The array of `ListRow` which will be converted into rows for this list. + * An array of ListRow objects that define the content and structure of each row in the list. */ data: ListRow[]; /** - * Whether or not more data is being loaded. Set this to `true` when paginating and fetching more data for the list. + * A boolean indicating whether more data is being loaded. Set to `true` when paginating and fetching additional data for the list. */ isLoadingMore?: boolean; /** - * The logic behind displaying an image or placeholder. `automatic` will display an image or placeholder if it detects - * that a `ListItem` in `data` has an `imageUri` value. `never` will never display images or placeholders. `always` will - * always display images or placeholders if `imageUri` is undefined or empty. + * The logic for displaying images or placeholders: + * - `automatic`: Displays images or placeholders only when it detects that a ListRow has an image source value. + * - `always`: Displays images or placeholders for all rows, even when image sources are undefined or empty. + * - `never`: Hides all images and placeholders, creating a text-only list layout. + * * @defaultValue `automatic` */ imageDisplayStrategy?: 'automatic' | 'always' | 'never'; /** - * Callback for when the user reaches the end of the `List`. This can be used to fire a request to load more data. + * A callback function executed when the user reaches the end of the list. Use this to trigger requests for loading additional data. */ onEndReached?: () => void; } diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/Navigator/Navigator.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/Navigator/Navigator.ts index 6433d76768..f3df321b14 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/Navigator/Navigator.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/Navigator/Navigator.ts @@ -1,11 +1,8 @@ import {createRemoteComponent} from '@remote-ui/core'; -/** - * @property `initialScreenName` sets the initial `Screen` whose `name` matches. - */ export interface NavigatorProps { /** - * Sets the initial `Screen` whose `name` matches. + * The name of the initial `Screen` component to display when the Navigator is first rendered. Must match the `name` property of a child `Screen` component. */ initialScreenName?: string; } diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/NumberField/NumberField.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/NumberField/NumberField.ts index 35900c5e65..4582d94f42 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/NumberField/NumberField.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/NumberField/NumberField.ts @@ -1,14 +1,20 @@ import {createRemoteComponent} from '@remote-ui/core'; import type {InputProps} from '../shared/InputField'; -/** - * Represents the properties for the NumberField component. - * @typedef {Object} NumberFieldProps - * @property {'decimal' | 'numeric'} [inputMode] - The mode of input, can be either 'decimal' or 'numeric'. - */ export interface NumberFieldProps extends InputProps { + /** + * The virtual keyboard layout to display: + * - `decimal`: A keyboard layout that includes decimal point support for entering fractional numbers, prices, or measurements with decimal precision. + * - `numeric`: A keyboard layout optimized for integer-only entry without decimal point support, ideal for quantities, counts, or whole number values. + */ inputMode?: 'decimal' | 'numeric'; + /** + * The highest decimal or integer to be accepted for the field. Users can still input higher numbers by keyboard—you must add appropriate validation logic. + */ max?: number; + /** + * The lowest decimal or integer to be accepted for the field. Users can still input lower numbers by keyboard—you must add appropriate validation logic. + */ min?: number; } diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/POSBlock/POSBlock.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/POSBlock/POSBlock.ts index 303edc2ffd..6f8c9b2243 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/POSBlock/POSBlock.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/POSBlock/POSBlock.ts @@ -1,26 +1,22 @@ import {createRemoteComponent} from '@remote-ui/core'; -/** - * Renders a `POSBlock`. Note that the text displayed on this `POSBlock` - * is dependent on the description of the extension. A `POSBlock` only - * accepts `POSBlockRow` as children. - */ export interface POSBlockProps { /** - * Sets an optional action button to be displayed on the `POSBlock`. + * An optional action button configuration to be displayed on the `POSBlock`. */ action?: { /** - * The title of the action button. + * The text displayed on the action button. Use clear, action-oriented language like "View Details" or "Update Status." */ title: string; /** - * Whether the action button is disabled. + * Controls whether the action button can be pressed. When `true`, the button is disabled and users cannot interact with it. + * * @defaultValue false */ disabled?: boolean; /** - * A callback that is called when the action button is pressed. + * A callback function executed when the action button is pressed. Use this to handle user interactions such as navigation or triggering specific actions. */ onPress: () => void; }; diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/POSBlock/POSBlockRow.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/POSBlock/POSBlockRow.ts index 645d5d3f96..0e45960296 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/POSBlock/POSBlockRow.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/POSBlock/POSBlockRow.ts @@ -1,11 +1,8 @@ import {createRemoteComponent} from '@remote-ui/core'; -/** - * Renders a `POSBlockRow` in a `POSBlock`. - */ export interface POSBlockRowProps { /** - * A callback for when the row is tapped. + * A callback function executed when the user taps the row. Use this to handle row-specific interactions or navigation. */ onPress?: () => void; } diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/PinPad/PinPad.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/PinPad/PinPad.ts index b7488f1188..a6f404b06e 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/PinPad/PinPad.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/PinPad/PinPad.ts @@ -1,72 +1,69 @@ import {createRemoteComponent} from '@remote-ui/core'; /** - * Represents the result of the pin pad onSubmit function. - * @typedef {('accept'|'reject')} PinValidationResult + * Defines the validation result values that the `onSubmit` callback must return to indicate PIN verification status. + * + * Available values: + * - `accept`: A validation result indicating the PIN is correct and authentication was successful. + * - `reject`: A validation result indicating the PIN is incorrect and authentication failed. */ export type PinValidationResult = 'accept' | 'reject'; /** - * Represents the allowed lengths of a PIN. - * @typedef {(4|5|6|7|8|9|10)} PinLength + * Defines the allowed PIN length values that constrain how many digits users can enter. + * + * Available lengths: + * - `4`: A four-digit PIN length, commonly used for basic security codes and quick authentication. + * - `5`: A five-digit PIN length for moderate security requirements. + * - `6`: A six-digit PIN length, commonly used for enhanced security codes and verification. + * - `7`: A seven-digit PIN length for higher security requirements. + * - `8`: An eight-digit PIN length for strong security and complex authentication scenarios. + * - `9`: A nine-digit PIN length for very high security requirements. + * - `10`: A ten-digit PIN length, the maximum supported for highly secure authentication workflows. */ export type PinLength = 4 | 5 | 6 | 7 | 8 | 9 | 10; /** - * Represents an action type for the PinPad component. - * @typedef {Object} PinPadActionType - * @property {string} label - The label for the action button. - * @property {function(): number[]} onPress - The function to be called when the action button is pressed. + * Defines the configuration object for action buttons displayed between the PIN entry view and keypad. */ export interface PinPadActionType { /** - * The label for the action button. + * The label text displayed on the action button. */ label: string; /** - * The function to be called when the action button is pressed. + * A callback function executed when the action button is pressed, returning the current PIN as an array of numbers. */ onPress: () => Promise; } -/** - * Represents the properties for the PinPad component. - * @typedef {Object} PinPadProps - * @property {boolean} [masked] - Whether the entered PIN should be masked. - * @property {PinLength} [minPinLength] - The minimum length of the PIN. - * @property {PinLength} [maxPinLength] - The maximum length of the PIN. - * @property {string} [label] - The content for the prompt on the pin pad. - * @property {PinPadActionType} [pinPadAction] - The call to action between the entry view and the keypad, consisting of a label and function that returns the pin. - * @property {function(pin: number[]): Promise} onSubmit - The function to be called when the PIN is submitted. - * @property {function(pin: number[]): void} [onPinEntry] - The function to be called when a PIN is entered. - */ export interface PinPadProps { /** - * Whether the entered PIN should be masked. + * Whether the entered PIN should be masked with dots or asterisks to protect privacy and security. */ masked?: boolean; /** - * The minimum length of the PIN. + * The minimum length of the PIN that users must enter before submission is allowed. */ minPinLength?: PinLength; /** - * The maximum length of the PIN. + * The maximum length of the PIN that users can enter, constraining the number of digits. */ maxPinLength?: PinLength; /** - * The content for the prompt on the pin pad. + * The content for the prompt displayed on the pin pad that instructs users what to enter. */ label?: string; /** - * The call to action between the entry view and the keypad, consisting of a label and function that returns the pin. + * A call-to-action configuration displayed between the entry view and the keypad, consisting of a label and function that returns the current PIN. */ pinPadAction?: PinPadActionType; /** - * The function to be called when the PIN is submitted. + * A callback function executed when the PIN is submitted, receiving the PIN as an array of numbers. Must return a Promise that resolves to either `'accept'` or `'reject'` to indicate validation success or failure. */ onSubmit: (pin: number[]) => Promise; /** - * The function to be called when a PIN is entered. + * A callback function executed when a PIN is entered, receiving the PIN as an array of numbers. Use this for real-time feedback or validation during PIN entry. */ onPinEntry?: (pin: number[]) => void; } diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/RadioButtonList/RadioButtonList.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/RadioButtonList/RadioButtonList.ts index b5297ef417..a1dc1d1d03 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/RadioButtonList/RadioButtonList.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/RadioButtonList/RadioButtonList.ts @@ -2,19 +2,19 @@ import {createRemoteComponent} from '@remote-ui/core'; export interface RadioButtonListProps { /** - * The radio button options. + * An array of string values representing the radio button options available for selection. */ items: string[]; /** - * A callback to be performed when the radio list item is selected. + * A callback function executed when a radio list item is selected, receiving the selected item string as a parameter. You must update the `initialSelectedItem` property in response to this callback to reflect the new selection. */ onItemSelected: (item: string) => void; /** - * The name of the selected item. Warning: This is a controlled component, so this prop must be used in conjunction with onItemSelected. + * The name of the currently selected item. You control the selection by setting this property and updating it when `onItemSelected` fires. */ initialSelectedItem?: string; /** - * Whether the initialSelectedItem renders at the top of the list. + * A boolean that determines whether the initially selected item renders at the top of the list, automatically scrolling to show the selected option. */ initialOffsetToShowSelectedItem?: boolean; } diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/Screen/Screen.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/Screen/Screen.ts index c0741893de..6316f4d768 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/Screen/Screen.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/Screen/Screen.ts @@ -1,82 +1,68 @@ import {createRemoteComponent} from '@remote-ui/core'; -/** Represents the presentation of a screen in the navigation stack. - * @property `sheet` displays the screen from the bottom on `navigate` when `true`. +/** + * Defines the presentation options for how the screen appears when navigated to. */ export interface ScreenPresentationProps { /** - * Displays the screen from the bottom on `navigate` when `true`. + * Displays the screen from the bottom as a sheet presentation when true during navigation. The text label displayed on the secondary action button in the screen's action bar. */ sheet?: boolean; } -/** Represents the secondary action button of a screen in the navigation stack. - * @property `text` displays the name of the secondary action in the action bar. - * @property `onPress` triggered when the secondary action button is pressed. - * @property `isEnabled` sets whether the action can be tapped. +/** + * Defines the configuration options for secondary action buttons displayed in the screen header. */ export interface SecondaryActionProps { /** - * Displays the name of the secondary action in the action bar. + * The text label displayed on the secondary action button in the screen's action bar. */ text: string; /** - * Triggered when the secondary action button is pressed. + * A callback function triggered when the secondary action button is pressed by the user. */ onPress: () => void; /** - * Sets whether the action can be tapped. + * Whether the secondary action button can be tapped and is interactive. */ isEnabled?: boolean; } -/** Represents a screen in the navigation stack. - * @property `name` used to identify this screen as a destination in the navigation stack. - * @property `title` the title of the screen which will be displayed on the UI. - * @property `isLoading` displays a loading indicator when `true`. Set this to `true` when performing an asynchronous task, and then to false when the data becomes available to the UI. - * @property `presentation` dictates how the `Screen` will be presented when navigated to. - * @property `secondaryAction` displays a secondary action button on the screen. - * @property `onNavigate` triggered when the screen is navigated to. - * @property `onNavigateBack` triggered when the user navigates back from this screen. Runs after screen is unmounted. - * @property `overrideNavigateBack` a callback that allows you to override the secondary navigation action. Runs when screen is mounted. - * @property `onReceiveParams` a callback that gets triggered when the navigation event completes and the screen receives the parameters. - */ export interface ScreenProps { /** - * Used to identify this screen as a destination in the navigation stack. + * The unique identifier used to identify this screen as a destination in the navigation stack. */ name: string; /** - * The title of the screen which will be displayed on the UI. + * The title text of the screen that will be displayed in the UI header. */ title: string; /** - * Displays a loading indicator when `true`. - * Set this to `true` when performing an asynchronous task, and then to false when the data becomes available to the UI. + * A boolean that displays a loading indicator when `true`. Set this during asynchronous tasks and return to `false` when data becomes available. */ isLoading?: boolean; /** - * Dictates how the `Screen` will be presented when navigated to. + * The presentation configuration that dictates how the screen will be displayed when navigated to. */ presentation?: ScreenPresentationProps; /** - * Displays a secondary action button on the screen. + * The configuration for a secondary action button displayed on the screen header. */ secondaryAction?: SecondaryActionProps; /** - * Triggered when the screen is navigated to. + * A callback function triggered when the screen is navigated to in the navigation stack. */ onNavigate?: () => void; /** - * Triggered when the user navigates back from this screen. Runs after screen is unmounted. + * A callback function triggered when the user navigates back from this screen. Runs after the screen is unmounted. */ onNavigateBack?: () => void; /** - * A callback that allows you to override the secondary navigation action. Runs when screen is mounted. + * A callback function that allows you to override the default back navigation action. Runs when the screen is mounted. */ overrideNavigateBack?: () => void; /** - * A callback that gets triggered when the navigation event completes and the screen receives the parameters. + * A callback function triggered when the navigation event completes and the screen receives parameters passed during navigation. */ onReceiveParams?: (params: any) => void; } diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/SearchBar/SearchBar.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/SearchBar/SearchBar.ts index fd9bb754d1..cac09188a5 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/SearchBar/SearchBar.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/SearchBar/SearchBar.ts @@ -2,27 +2,31 @@ import {createRemoteComponent} from '@remote-ui/core'; export interface SearchBarProps { /** - * The initial text value in the search bar. This is different from `placeHolder`, which is displayed in the search bar when the search bar doesn't have a populated string. + * The initial text value displayed in the search bar when first rendered. This differs from placeholder text which appears when the field is empty. */ initialValue?: string; /** - * A callback containing the new text value of the search bar. + * A callback function executed whenever the text value changes, receiving the new text value as a parameter for real-time search or filtering. */ onTextChange?: (value: string) => void; /** - * A callback when the search button is tapped. + * A callback function executed when the search button is tapped, receiving the current search text as a parameter. */ onSearch: (value: string) => void; /** - * A callback when the input is focused. + * A callback function executed when the search input field receives focus. */ onFocus?: () => void; /** - * Whether the text can be changed. + * A callback function executed when focus is removed from the search input field. + */ + onBlur?: () => void; + /** + * Whether the text can be changed by user input. */ editable?: boolean; /** - * The placeholder value to display in the search bar when no text is entered. + * The placeholder text displayed in the search bar when no text is entered, providing guidance about what users can search for. */ placeholder?: string; } diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/Section/Section.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/Section/Section.ts index 71055e0141..5317d65bd4 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/Section/Section.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/Section/Section.ts @@ -1,31 +1,26 @@ import {createRemoteComponent} from '@remote-ui/core'; -/** Allows the implementation of an action at the top right of a `Section`. - * @property `title` the title describing the action. - * @property `onPress` the callback when the action is tapped by the user. +/** + * Defines the configuration object for the action button displayed within the section header. */ export interface SectionHeaderAction { /** - * The title describing the action. + * The title text describing the action that will be displayed on the button. */ title: string; /** - * The callback when the action is tapped by the user. + * A callback function that is executed when the action button is pressed by the user. */ onPress: () => void; } -/** Renders content that is bound by a border, with a title and a call to action at the top. - * @property `title` the title of the section. - * @property `action` the action in the top right of the section that can be triggered by a tap. - */ export interface SectionProps { /** - * The title of the section. + * The title text displayed at the top of the section to describe its content. */ title?: string; /** - * The action in the top right of the section that can be triggered by a tap. + * An optional action configuration displayed in the top right of the section that can be triggered by user interaction. */ action?: SectionHeaderAction; } diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/SectionHeader/SectionHeader.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/SectionHeader/SectionHeader.ts index 741d7cbb27..c7319f9ed5 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/SectionHeader/SectionHeader.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/SectionHeader/SectionHeader.ts @@ -2,28 +2,28 @@ import {createRemoteComponent} from '@remote-ui/core'; export interface SectionHeaderProps { /** - * Title to be displayed. + * The title text displayed in the section header. Provide clear, descriptive text that accurately represents the content section below. */ title: string; /** - * Action button to be displayed. The SectionHeader must have a `title` for `action` to work. + * An optional action button configuration to be displayed alongside the title. The `SectionHeader` must have a title for the action to work properly. */ action?: { /** - * Label for the action button. + * The label text displayed on the action button. Use clear, descriptive labels like "Edit Settings" or "Add Item." */ label: string; /** - * Function to handle action button press. + * A callback function executed when the action button is pressed. Use this to handle user interactions such as navigation or triggering specific actions. */ onPress: () => void; /** - * Whether or not the action button is disabled. + * Controls whether the action button can be pressed. When `true`, the button is disabled and users can't interact with it. */ disabled?: boolean; }; /** - * Whether or not the divider line under the SectionHeader should be hidden. + * Whether the divider line under the `SectionHeader` should be hidden. */ hideDivider?: boolean; } diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/SegmentedControl/SegmentedControl.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/SegmentedControl/SegmentedControl.ts index fde3c9f279..779c4a1d48 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/SegmentedControl/SegmentedControl.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/SegmentedControl/SegmentedControl.ts @@ -1,31 +1,33 @@ import {createRemoteComponent} from '@remote-ui/core'; - +/** + * Defines the structure and configuration options for individual segments within the `SegmentedControl` component. + */ export interface Segment { /** - * The id of the segment. + * The unique identifier for the segment used for selection tracking and callback identification. */ id: string; /** - * The label of the segment. + * The text label displayed on the segment that users see and interact with. */ label: string; /** - * Whether the segment is disabled. + * Whether the segment is disabled and non-interactive. */ disabled: boolean; } export interface SegmentedControlProps { /** - * The segments to display. + * An array of segment objects that define the available options in the segmented control. */ segments: Segment[]; /** - * The id of the selected segment. + * The ID of the currently selected segment that determines which option is visually highlighted. */ selected: string; /** - * A callback when a segment is selected. + * A callback function executed when a segment is selected, receiving the selected segment's id as a parameter. */ onSelect: (id: string) => void; } diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/Selectable/Selectable.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/Selectable/Selectable.ts index 601b2909bf..2163aa948a 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/Selectable/Selectable.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/Selectable/Selectable.ts @@ -2,11 +2,11 @@ import {createRemoteComponent} from '@remote-ui/core'; export interface SelectableProps { /** - * The callback on press. + * The callback function that's executed when the user taps or presses the selectable component. This is the primary way to handle user interactions with the wrapped content. The function receives no parameters and should contain the logic for what happens when the selection occurs, such as navigation, state updates, or triggering other actions. */ onPress: () => void; /** - * Whether the selectable reacts to presses. + * Controls whether the selectable component responds to user interactions. When set to `true`, the component won't react to taps or presses, the `onPress` callback won't be triggered, and the wrapped content appears non-interactive. Use this to temporarily disable selection during loading states, form validation, or when certain conditions aren't met. When `false` or undefined, the component responds normally to user interactions. */ disabled?: boolean; } diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/Stepper/Stepper.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/Stepper/Stepper.ts index 064bf4ec16..7ba814a32e 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/Stepper/Stepper.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/Stepper/Stepper.ts @@ -2,33 +2,35 @@ import {createRemoteComponent} from '@remote-ui/core'; export interface StepperProps { /** - * The initial value of the stepper. + * The initial value of the stepper that sets the starting numeric value when the component is first rendered. */ initialValue: number; /** - * A callback when the value of the stepper changes. + * A callback function executed when the value of the stepper changes, receiving the new numeric value as a parameter. */ onValueChanged: (value: number) => void; /** - * Use to set the minimum value of the stepper. + * The minimum value that the stepper can reach. When the value equals the minimum, the decrement button will be disabled. + * * @defaultValue 1 */ minimumValue?: number; /** - * Use to set the maximum value of the stepper. + * The maximum value that the stepper can reach. When the value equals the maximum, the increment button will be disabled. */ maximumValue?: number; /** - * Only use this field if you wish to override the internal state of this component. + * An optional value to override the internal state of the component. Only use this if you need complete control over the stepper's value from external state. */ value?: number; /** - * Whether the field can be modified. + * Whether the field can be modified, disabling both increment and decrement buttons. + * * @defaultValue false */ disabled?: boolean; diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/Text/Text.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/Text/Text.ts index 013f74af3e..75867d8a33 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/Text/Text.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/Text/Text.ts @@ -1,5 +1,18 @@ import {createRemoteComponent} from '@remote-ui/core'; +/** + * Defines the typography hierarchy options for text elements. Each variant provides specific sizing, weight, and styling appropriate for different content types. + * + * Available variants: + * - `sectionHeader`: A section header variant for titles that organize and introduce content sections. + * - `captionRegular`: A regular caption variant for supplementary text, labels, or secondary information. + * - `captionRegularTall`: A taller caption variant with increased line height for improved readability in dense layouts. + * - `captionMedium`: A medium-weight caption variant for slightly emphasized secondary text or important labels. + * - `body`: The standard body text variant for primary content, descriptions, and general text. + * - `headingSmall`: A small heading variant for subsection titles and secondary headings. + * - `headingLarge`: A large heading variant for main section titles and primary headings. + * - `display`: The largest display variant for prominent titles, hero text, or major interface elements. + */ export type TextVariant = | 'sectionHeader' | 'captionRegular' @@ -10,6 +23,19 @@ export type TextVariant = | 'headingLarge' | 'display'; +/** + * Defines the semantic color options for text elements. Each color conveys specific meaning and intent through visual styling. + * + * Available colors: + * - `TextNeutral`: A neutral text color for general content that doesn't convey specific semantic meaning. + * - `TextSubdued`: A subdued text color for secondary information, captions, or content that should be less prominent. + * - `TextDisabled`: A disabled text color for inactive or unavailable content that users can't interact with. + * - `TextWarning`: A warning text color for cautionary messages or content that requires user attention. + * - `TextCritical`: A critical text color for errors, failures, or destructive actions that require immediate attention. + * - `TextSuccess`: A success text color for positive outcomes, confirmations, or completed actions. + * - `TextInteractive`: An interactive text color for clickable elements, links, or content that users can interact with. + * - `TextHighlight`: A highlight text color for emphasized content that needs to stand out or draw special attention. + */ export type ColorType = | 'TextNeutral' | 'TextSubdued' @@ -22,11 +48,11 @@ export type ColorType = export interface TextProps { /** - * The text variant. + * The typography variant that determines the size, weight, and styling of the text within the design system hierarchy. */ variant?: TextVariant; /** - * The text color. + * The semantic color of the text that conveys meaning and intent through visual styling. */ color?: ColorType; } diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/TextArea/TextArea.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/TextArea/TextArea.ts index ffe4a8feaa..8a6b09bab6 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/TextArea/TextArea.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/TextArea/TextArea.ts @@ -1,14 +1,9 @@ import {createRemoteComponent} from '@remote-ui/core'; import type {InputProps} from '../shared/InputField'; -/** - * Represents the properties for the TextField component. - * @typedef {Object} TextAreaProps - * @property {number} [rows] - The initial number of lines to be displayed. Maximum of 8 lines. - */ export interface TextAreaProps extends InputProps { /** - * The initial number of lines to be displayed. Maximum of 8 lines. + * The initial number of visible text lines to be displayed. Maximum of 8 lines. */ rows?: number; } diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/TextField/TextField.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/TextField/TextField.ts index b1d8745745..14476d0a9f 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/TextField/TextField.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/TextField/TextField.ts @@ -3,24 +3,54 @@ import type {BaseTextFieldProps} from '../shared/BaseTextField'; import type {InputProps} from '../shared/InputField'; export interface ActionProps { + /** + * Identifies this as an action-type embedded element. + */ type: 'action'; + /** + * The message or label text displayed for the action. + */ message: string; + /** + * A callback function executed when the action button is pressed, receiving the current field value as a parameter. + */ onPress: (value: string) => void; } export interface InfoProps { + /** + * Identifies this as an info-type embedded element. + */ type: 'info'; + /** + * The informational message text to display to the user. + */ message: string; + /** + * Controls whether the info message is always visible or only shown under certain conditions. + */ alwaysShow?: boolean; } export interface SuccessProps { + /** + * Identifies this as a success-type embedded element. + */ type: 'success'; + /** + * An optional success message to display when the field validation or operation succeeds. + */ message?: string; } export interface PasswordProps { + /** + * Identifies this as a password-type embedded element. + */ type: 'password'; + /** + * A callback function executed when the password action button is pressed, receiving the current field value as a parameter. + */ onPress: (value: string) => void; } diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/Tile/Tile.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/Tile/Tile.ts index 0a98f46127..ab693ddc33 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/Tile/Tile.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/Tile/Tile.ts @@ -1,37 +1,28 @@ import {createRemoteComponent} from '@remote-ui/core'; -/** - * @property `title` the text set on the main label of the tile. - * @property `subtitle` the text set on the secondary label of the tile. - * @property `enabled` sets whether or not the tile can be tapped. - * @property `destructive` sets whether or not the tile has a destructive appearance and active state as of POS - * 10.0.0. - * @property `badgeValue` the number value displayed in the top right corner of the tile. - * @property `onPress` the callback that is executed when the tile is tapped. - */ export interface TileProps { /** - * The text set on the main label of the tile. + * The text displayed as the main label of the tile. */ title: string; /** - * The text set on the secondary label of the tile. + * The text displayed as the secondary label below the title. */ subtitle?: string; /** - * Sets whether or not the tile can be tapped. + * Whether the tile can be tapped and responds to user interaction. When disabled, the tile appears dimmed and doesn't respond to tap events. */ enabled?: boolean; /** - * Sets whether or not the tile is in a red destructive appearance. + * Sets whether the tile appears in a destructive/warning state. As of POS 10.0.0, this property creates an "active state" appearance rather than just red coloring. */ destructive?: boolean; /** - * The number value displayed in the top right corner of the tile. + * A numeric value displayed as a small badge in the top right corner of the tile. */ badgeValue?: number; /** - * The callback that is executed when the tile is tapped. + * The callback function that's executed when users tap the tile. */ onPress?: () => void; } diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/TimeField/TimeField.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/TimeField/TimeField.ts index dd92aa3270..bbbfd48a35 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/TimeField/TimeField.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/TimeField/TimeField.ts @@ -15,7 +15,8 @@ export interface TimeFieldProps | 'helpText' > { /** - * (Android only) Whether the clock displays in 24 hour time instead of 12 hour time. + * Whether the clock displays in 24-hour format instead of 12-hour format. This property only affects Android devices. + * * @defaultValue false */ is24Hour?: boolean; diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/TimePicker/TimePicker.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/TimePicker/TimePicker.ts index e692418482..369cdff932 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/TimePicker/TimePicker.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/TimePicker/TimePicker.ts @@ -1,17 +1,10 @@ import {createRemoteComponent} from '@remote-ui/core'; -/** - * Represents the properties for the TimePicker component. - * @property selected - The selected time. - * @property onChange - A callback for changes. - * @property visibleState - Controls the visible state, and a callback to set the visible state as false when the dialog closes. - * @property is24Hour - (Android only) Whether the clock displays in 24 hour time instead of 12 hour time. - * @property inputMode - Whether to display the picker in inline (clock) mode or spinner mode. - */ export interface TimePickerProps { /** - * The selected time. - * @defaultValue The current time + * The currently selected time value. Defaults to the current time when not specified. + * + * @defaultValue The current time. */ selected?: string; /** @@ -19,17 +12,20 @@ export interface TimePickerProps { */ onChange?(selected: string): void; /** - * Controls the visible state, and a callback to set the visible state as false when the dialog closes. + * A tuple that controls the visible state of the picker and provides a callback to set visibility to false when the dialog closes. The first element is the current visibility state, and the second is a setter function. */ visibleState: [boolean, (visible: boolean) => void]; /** - * (Android only) Whether the clock displays in 24 hour time instead of 12 hour time. + * Whether the clock displays in 24-hour format instead of 12-hour format. This property only affects Android devices. + * * @defaultValue false */ is24Hour?: boolean; /** - * Whether to display the picker in inline (clock) mode or spinner mode. - * iOS only supports 'spinner'. + * The display mode for the time picker. + * - `inline`: A clock-style interface that displays an analog or digital clock where users can tap to select specific times. Provides visual context about time relationships. Only available on Android devices—iOS always uses spinner mode. + * - `spinner`: A spinner-style selector with scrollable columns for hours, minutes, and optionally seconds. Offers a more compact interface suitable for all devices and is the only mode supported on iOS. + * * @defaultValue 'inline' */ inputMode?: 'inline' | 'spinner'; diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/shared/BaseTextField.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/shared/BaseTextField.ts index 93990ca973..111852a52a 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/shared/BaseTextField.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/shared/BaseTextField.ts @@ -1,34 +1,26 @@ -/** - * @property `title` the title of the `TextField`. - * @property `initialValue` populates the `TextField` with an text initial value. - * @property `placeholder` sets a placeholder value for when the `TextField` is empty. - * @property `isValid` set whether the current value in the `TextField` is valid. - * @property `errorMessage` sets an error message to present to the user. - * @property `onChangeText` a callback that is executed every time the `TextField` value changes. - */ export interface BaseTextFieldProps { /** - * The title of the `TextField`. + * The title text displayed for the text field. */ title?: string; /** - * Populates the `TextField` with an text initial value. + * The initial text value to populate the text field with when it first renders. */ initialValue?: string; /** - * Sets a placeholder value for when the `TextField` is empty. + * A placeholder hint displayed when the text field is empty. */ placeholder?: string; /** - * Set whether the current value in the `TextField` is valid. + * Controls the validation state of the current value in the text field. When `false`, indicates invalid input. */ isValid?: boolean; /** - * Sets an error message to present to the user. + * An error message to display to the user when validation fails. */ errorMessage?: string; /** - * A callback that is executed every time the `TextField` value changes. + * A callback function executed every time the text field value changes, receiving the new value as a parameter. */ onChangeText?: (value: string) => void; } diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/shared/InputField.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/shared/InputField.ts index 040d809d23..b87d58c164 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/shared/InputField.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/shared/InputField.ts @@ -1,69 +1,48 @@ /** - * Represents an action type for the text field components. - * @typedef {Object} InputAction - * @property {string} label - The text displayed in the button. - * @property {boolean} [disabled] - Whether the button is disabled. - * @property {function(): void} onPress - A callback to be performed. + * Defines the configuration object for action buttons displayed below input fields to provide extra functionality. */ export interface InputAction { /** - * The text displayed in the button. + * The text displayed on the action button. */ label: string; /** - * A callback to be performed. + * A callback function executed when the action button is pressed. */ onPress: () => void; /** - * Whether the button can be pressed. + * Whether the action button can be pressed. */ disabled?: boolean; } -/** - * Represents the properties for the text field components. - * @typedef {Object} InputProps - * @property {boolean} [disabled] - Whether the field is disabled. - * @property {string} [error] - Indicate an error to the user. The field will be given a specific stylistic treatment to communicate problems that have to be resolved immediately. - * @property {string} [label] - Content to use as the field label. - * @property {function(): void} [onBlur] - Callback when focus is blurred. - * @property {function(value: string): void} [onChange] - Callback when the user has finished editing a field. - * @property {function(): void} [onFocus] - Callback when input is focused. - * @property {function(value: string): void} [onInput] - Callback when the user makes any changes in the field. As noted in the documentation for `onChange`, you **must not** use this to update `value` — use the `onChange` callback for that purpose. Use the `onInput` prop when you need to do something as soon as the user makes a change, like clearing validation errors that apply to the field as soon as the user begins making the necessary adjustments. - * @property {string} [placeholder] - A short hint that describes the expected value of the field. - * @property {boolean} [required] - Whether the field needs a value. - * @property {string} [value] - The current value for the field. If omitted, the field will be empty. You should update this value in response to the `onChange` callback. - * @property {string} [helpText] - Label under the text field which provides guidance or instructions that assist users. - * @property {InputAction} [action] - A button under the text field to provide extra functionality. - * @property {number?} [maxLength] - Specifies the maximum number of characters allowed. - */ export interface InputProps { /** - * Whether the field can be modified. + * Controls whether the field can be modified. When `true`, the field is disabled and users cannot edit its value. */ disabled?: boolean; /** - * Indicates an error to the user. The field is given specific stylistic treatment to communicate problems that have to be resolved immediately. + * An error message that indicates a problem to the user. The field is given specific stylistic treatment to communicate issues that must be resolved immediately. */ error?: string; /** - * The content to use as the field label. + * The content to use as the field label that describes the text information being requested. */ label: string; /** - * The callback when focus is removed. + * A callback function executed when focus is removed from the field. */ onBlur?: () => void; /** - * The callback when the user has finished editing a field. + * A callback function executed when the user has finished editing the field, receiving the new text value as a parameter. You should update the `value` property in response to this callback. */ onChange?: (value: string) => void; /** - * The callback when input is focused. + * A callback function executed when the field receives focus. */ onFocus?: () => void; /** - * Callback when the user makes any changes in the field. As noted in the documentation for `onChange`, you **must not** use this to update `value` — use the `onChange` callback for that purpose. Use the `onInput` prop when you need to do something as soon as the user makes a change, like clearing validation errors that apply to the field as soon as the user begins making the necessary adjustments. + * A callback function executed immediately when the user makes any change in the field. Use this for real-time feedback, such as clearing validation errors as soon as the user begins making corrections. Don't use this to update the `value` property—the `onChange` callback is the appropriate handler for updating the field's value. */ onInput?: (value: string) => void; /** @@ -71,23 +50,23 @@ export interface InputProps { */ placeholder?: string; /** - * Whether the field needs a value. + * Whether the field needs a value for form submission or validation purposes. */ required?: boolean; /** - * The current value for the field. Defaults to now. You should update this value in response to the `onChange` callback. + * The current text value for the field. If omitted, the field will be empty. You should update the `value` property in response to the `onChange` callback. */ value?: string; /** - * The label under the text field which provides guidance or instructions that assist users. + * The label text displayed under the field that provides guidance or instructions to assist users. */ helpText?: string; /** - * A button under the text field to provide extra functionality. + * A button configuration object displayed under the text field to provide extra functionality. */ action?: InputAction; /** - * The maximum number of characters allowed in the input field. + * The maximum number of characters allowed in the text field. */ maxLength?: number; } diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/targets.ts b/packages/ui-extensions/src/surfaces/point-of-sale/targets.ts index 9b4a7351c3..dc2bfa1784 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/targets.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/targets.ts @@ -37,29 +37,117 @@ type BlockComponents = AnyComponentBuilder< >; export interface ExtensionTargets { + /** + * Renders a single interactive tile component on the POS home screen's smart grid. The tile appears once during home screen initialization and remains persistent until navigation occurs. Use this target for high-frequency actions, status displays, or entry points to workflows that merchants need daily. + * + * Extensions at this target can dynamically update properties like enabled state and badge values in response to cart changes or device conditions. Tiles typically invoke `api.action.presentModal()` to launch the companion modal for complete workflows. + */ 'pos.home.tile.render': RenderExtension< // eslint-disable-next-line import/no-deprecated StandardApi<'pos.home.tile.render'> & SmartGridApi & ActionApi & CartApi, SmartGridComponents >; + /** + * Renders a full-screen modal interface launched from smart grid tiles. The modal appears when users tap a companion tile. Use this target for complete workflow experiences that require more space and functionality than the tile interface provides, such as multi-step processes, detailed information displays, or complex user interactions. + * + * Extensions at this target support full navigation hierarchies with multiple screens, scroll views, and interactive components to handle sophisticated workflows. + */ 'pos.home.modal.render': RenderExtension< ActionTargetApi<'pos.home.modal.render'> & CartApi, BasicComponents >; + /** + * Renders a single interactive button component as a menu item in the post-return action menu. Use this target for post-return operations like generating return receipts, processing restocking workflows, or collecting return feedback. + * + * Extensions at this target can access the order identifier through the Order API to perform return-specific operations. Menu items typically invoke `api.action.presentModal()` to launch the companion modal for complete post-return workflows. + */ + 'pos.return.post.action.menu-item.render': RenderExtension< + StandardApi<'pos.return.post.action.menu-item.render'> & + ActionApi & + OrderApi, + ActionComponents + >; + /** + * Renders a full-screen modal interface launched from post-return menu items. Use this target for complex post-return workflows that require forms, multi-step processes, or detailed information displays beyond what a simple button can provide. + * + * Extensions at this target have access to order data through the Order API and support workflows with multiple screens, navigation, and interactive components. + */ + 'pos.return.post.action.render': RenderExtension< + ActionTargetApi<'pos.return.post.action.render'> & OrderApi, + BasicComponents + >; + /** + * Renders a custom information section within the post-return screen. Use this target for displaying supplementary return data like completion status, refund confirmations, or follow-up workflows alongside standard return details. + * + * Extensions at this target appear as persistent blocks within the post-return interface and support interactive elements that can launch modal workflows using `api.action.presentModal()` for more complex post-return operations. + */ + 'pos.return.post.block.render': RenderExtension< + StandardApi<'pos.return.post.block.render'> & OrderApi & ActionApi, + BlockComponents + >; + /** + * Renders a single interactive button component as a menu item in the post-exchange action menu. Use this target for post-exchange operations like generating exchange receipts, processing restocking workflows, or collecting exchange feedback. + * + * Extensions at this target can access the order identifier through the Order API to perform exchange-specific operations. Menu items typically invoke `api.action.presentModal()` to launch the companion modal for complete post-exchange workflows. + */ + 'pos.exchange.post.action.menu-item.render': RenderExtension< + StandardApi<'pos.exchange.post.action.menu-item.render'> & + ActionApi & + OrderApi, + ActionComponents + >; + /** + * Renders a full-screen modal interface launched from post-exchange menu items. Use this target for complex post-exchange workflows that require forms, multi-step processes, or detailed information displays beyond what a simple button can provide. + * + * Extensions at this target have access to order data through the Order API and support workflows with multiple screens, navigation, and interactive components. + */ + 'pos.exchange.post.action.render': RenderExtension< + ActionTargetApi<'pos.exchange.post.action.render'> & OrderApi, + BasicComponents + >; + /** + * Renders a custom information section within the post-exchange screen. Use this target for displaying supplementary exchange data like completion status, payment adjustments, or follow-up workflows alongside standard exchange details. + * + * Extensions at this target appear as persistent blocks within the post-exchange interface and support interactive elements that can launch modal workflows using `api.action.presentModal()` for more complex post-exchange operations. + */ + 'pos.exchange.post.block.render': RenderExtension< + StandardApi<'pos.exchange.post.block.render'> & OrderApi & ActionApi, + BlockComponents + >; + /** + * Renders a single interactive button component as a menu item in the post-purchase action menu. Use this target for post-purchase operations like sending receipts, collecting customer feedback, or launching follow-up workflows after completing a sale. + * + * Extensions at this target can access the order identifier through the Order API to perform purchase-specific operations. Menu items typically invoke `api.action.presentModal()` to launch the companion modal for complete post-purchase workflows. + */ 'pos.purchase.post.action.menu-item.render': RenderExtension< StandardApi<'pos.purchase.post.action.menu-item.render'> & ActionApi & OrderApi, ActionComponents >; + /** + * Renders a full-screen modal interface launched from post-purchase menu items. Use this target for complex post-purchase workflows that require forms, multi-step processes, or detailed information displays beyond what a simple button can provide. + * + * Extensions at this target have access to order data through the Order API and support workflows with multiple screens, navigation, and interactive components. + */ 'pos.purchase.post.action.render': RenderExtension< ActionTargetApi<'pos.purchase.post.action.render'> & OrderApi, BasicComponents >; + /** + * Renders a custom information section within the post-purchase screen. Use this target for displaying supplementary purchase data like completion status, customer feedback prompts, or next-step workflows alongside standard purchase details. + * + * Extensions at this target appear as persistent blocks within the post-purchase interface and support interactive elements that can launch modal workflows using `api.action.presentModal()` for more complex post-purchase operations. + */ 'pos.purchase.post.block.render': RenderExtension< StandardApi<'pos.purchase.post.block.render'> & OrderApi & ActionApi, BlockComponents >; + /** + * Renders a single interactive button component as a menu item in the product details action menu. Use this target for product-specific operations like inventory adjustments, product analytics, or integration with external product management systems. + * + * Extensions at this target can access the product identifier through the Product API to perform product-specific operations. Menu items typically invoke `api.action.presentModal()` to launch the companion modal for complete product workflows. + */ 'pos.product-details.action.menu-item.render': RenderExtension< StandardApi<'pos.product-details.action.menu-item.render'> & ActionApi & @@ -67,10 +155,20 @@ export interface ExtensionTargets { ProductApi, ActionComponents >; + /** + * Renders a full-screen modal interface launched from product details menu items. Use this target for complex product workflows that require forms, multi-step processes, or detailed information displays beyond what a simple button can provide. + * + * Extensions at this target have access to product and cart data through the Product API and support workflows with multiple screens, navigation, and interactive components. + */ 'pos.product-details.action.render': RenderExtension< ActionTargetApi<'pos.product-details.action.render'> & CartApi & ProductApi, BasicComponents >; + /** + * Renders a custom information section within the product details screen. Use this target for displaying supplementary product data like detailed specifications, inventory status, or related product recommendations alongside standard product details. + * + * Extensions at this target appear as persistent blocks within the product details interface and support interactive elements that can launch modal workflows using `api.action.presentModal()` for more complex product operations. + */ 'pos.product-details.block.render': RenderExtension< StandardApi<'pos.product-details.block.render'> & CartApi & @@ -78,6 +176,11 @@ export interface ExtensionTargets { ActionApi, BlockComponents >; + /** + * Renders a single interactive button component as a menu item in the order details action menu. Use this target for order-specific operations like reprints, refunds, exchanges, or launching fulfillment workflows. + * + * Extensions at this target can access the order identifier through the Order API to perform order-specific operations. Menu items typically invoke `api.action.presentModal()` to launch the companion modal for complete order workflows. + */ 'pos.order-details.action.menu-item.render': RenderExtension< StandardApi<'pos.order-details.action.menu-item.render'> & ActionApi & @@ -85,10 +188,20 @@ export interface ExtensionTargets { OrderApi, ActionComponents >; + /** + * Renders a full-screen modal interface launched from order details menu items. Use this target for complex order workflows that require forms, multi-step processes, or detailed information displays beyond what a simple button can provide. + * + * Extensions at this target have access to order data through the Order API and support workflows with multiple screens, navigation, and interactive components. + */ 'pos.order-details.action.render': RenderExtension< ActionTargetApi<'pos.order-details.action.render'> & CartApi & OrderApi, BasicComponents >; + /** + * Renders a custom information section within the order details screen. Use this target for displaying supplementary order data like fulfillment status, tracking numbers, or custom order analytics alongside standard order details. + * + * Extensions at this target appear as persistent blocks within the order details interface and support interactive elements that can launch modal workflows using `api.action.presentModal()` for more complex order operations. + */ 'pos.order-details.block.render': RenderExtension< StandardApi<'pos.order-details.block.render'> & CartApi & @@ -96,6 +209,11 @@ export interface ExtensionTargets { ActionApi, BlockComponents >; + /** + * Renders a single interactive button component as a menu item in the draft order details action menu. Use this target for draft order-specific operations like sending invoices, updating payment status, or launching custom workflow processes for pending orders. + * + * Extensions at this target can access draft order information including order ID, name, and associated customer through the Draft Order API. Menu items typically invoke `api.action.presentModal()` to launch the companion modal for complete draft order workflows. + */ 'pos.draft-order-details.action.menu-item.render': RenderExtension< StandardApi<'pos.draft-order-details.action.menu-item.render'> & ActionApi & @@ -103,12 +221,22 @@ export interface ExtensionTargets { DraftOrderApi, ActionComponents >; + /** + * Renders a full-screen modal interface launched from draft order details menu items. Use this target for complex draft order workflows that require forms, multi-step processes, or detailed information displays beyond what a simple button can provide. + * + * Extensions at this target have access to draft order data through the Draft Order API and support workflows with multiple screens, navigation, and interactive components. + */ 'pos.draft-order-details.action.render': RenderExtension< ActionTargetApi<'pos.draft-order-details.action.render'> & DraftOrderApi & CartApi, BasicComponents >; + /** + * Renders a custom information section within the draft order details screen. Use this target for displaying supplementary order information like processing status, payment status, or workflow indicators alongside standard draft order details. + * + * Extensions at this target appear as persistent blocks within the draft order interface and support interactive elements that can launch modal workflows using `api.action.presentModal()` for more complex draft order operations. + */ 'pos.draft-order-details.block.render': RenderExtension< StandardApi<'pos.draft-order-details.block.render'> & ActionApi & @@ -116,6 +244,11 @@ export interface ExtensionTargets { DraftOrderApi, ActionComponents >; + /** + * Renders a single interactive button component as a menu item in the customer details action menu. Use this target for customer-specific operations like applying customer discounts, processing loyalty redemptions, or launching profile update workflows. + * + * Extensions at this target can access the customer identifier through the Customer API to perform customer-specific operations. Menu items typically invoke `api.action.presentModal()` to launch the companion modal for complete customer workflows. + */ 'pos.customer-details.action.menu-item.render': RenderExtension< StandardApi<'pos.customer-details.action.menu-item.render'> & ActionApi & @@ -123,12 +256,22 @@ export interface ExtensionTargets { CustomerApi, ActionComponents >; + /** + * Renders a full-screen modal interface launched from customer details menu items. Use this target for complex customer workflows that require forms, multi-step processes, or detailed information displays beyond what a simple button can provide. + * + * Extensions at this target have access to customer data through the Customer API and support workflows with multiple screens, navigation, and interactive components. + */ 'pos.customer-details.action.render': RenderExtension< ActionTargetApi<'pos.customer-details.action.render'> & CartApi & CustomerApi, BasicComponents >; + /** + * Renders a custom information section within the customer details screen. Use this target for displaying supplementary customer data like loyalty status, points balance, or personalized information alongside standard customer details. + * + * Extensions at this target appear as persistent blocks within the customer details interface and support interactive elements that can launch modal workflows using `api.action.presentModal()` for more complex customer operations. + */ 'pos.customer-details.block.render': RenderExtension< StandardApi<'pos.customer-details.block.render'> & CartApi &