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..9e760d5618 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..d93e52dc29 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,233 @@ 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: ` +- **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 \`bulkCartUpdate\`, \`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..5aa99bfba6 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..92d0e88295 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..be889d69ac 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..6a77e77e86 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..3244d2d1cf 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..fe4ae432e5 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..da05c6f895 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/print-api.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/print-api.doc.ts index ec83d3e57a..8034eb76fa 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/print-api.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/print-api.doc.ts @@ -9,54 +9,80 @@ const generateCodeBlockForPrintApi = (title: string, fileName: string) => const data: ReferenceEntityTemplateSchema = { name: 'Print API', - description: `The Print API enables document printing through the device's native print dialog (such as AirPrint on iOS or the system print dialog on Android). This API is designed for printing documents to standard printers, and does not support direct printing to receipt printers.`, + description: + 'The Print API enables document printing functionality in your POS UI extension. Use this API to trigger the native print dialog for your documents.' + + '\n\nSupported document types:' + + '\n\n- **HTML documents** (`.html`, `.htm`) - Best printing experience with full CSS styling, embedded images, and complex layouts. Use for receipts, invoices, and formatted reports.' + + '\n- **Text files** (`.txt`, `.csv`) - Plain text with basic content and tabular data support. Use for simple receipts and data exports.' + + '\n- **Image files** (`.png`, `.jpg`, `.jpeg`, `.gif`, `.bmp`, `.webp`) - Common web formats with format-specific optimizations. Use for logos, charts, QR codes, and barcodes.' + + '\n- **PDF files** (`.pdf`) - Behavior varies by platform: prints directly on iOS/desktop, but downloads to external viewer on Android. Use for complex documents and compliance requirements.', isVisualComponent: false, type: 'APIs', definitions: [ { title: 'PrintApi', - description: 'Interface for handling print operations', + description: + 'The `PrintApi` object provides methods for triggering document printing. Access these methods through `api.print` to initiate print operations with various document types.', type: 'PrintApiContent', }, ], - category: 'APIs', - related: [ - { - name: 'PrintPreview Component', - subtitle: 'Preview documents before printing', - url: '/api/pos-ui-extensions/components/printpreview', - }, - { - name: 'Build a Print Extension', - subtitle: 'Learn how to implement printing', - url: '/docs/api/pos-ui-extensions/examples/print-extension', - }, - ], + category: 'Target APIs', + subCategory: 'Platform APIs', + related: [], examples: { - description: 'Examples of using the Print API', + description: + 'Learn how to trigger print operations for documents, receipts, and reports using various file formats and URL types.', examples: [ { codeblock: generateCodeBlockForPrintApi( - 'Print directly from the tile', + 'Print a document from a tile', 'print', ), + description: + 'Trigger the native print dialog directly from a tile interaction. This example demonstrates using `api.print()` to initiate printing from a tile tap, enabling quick access to print functionality for receipts, reports, or other documents without requiring modal navigation.', }, { codeblock: generateTSXCodeBlock( - 'Print with relative path', + 'Print using a relative file path', 'print-api', 'print-relative', ), + description: + 'Print documents using relative file paths within your extension. This example shows how to use `api.print()` with relative URLs to access documents bundled with your extension, ideal for printing static templates, pre-formatted receipts, or embedded resources.', }, { codeblock: generateTSXCodeBlock( - 'Print with full URL', + 'Print using an external URL', 'print-api', 'print-full-url', ), + description: + 'Print documents from external URLs or dynamically generated content. This example demonstrates using `api.print()` with full URLs to print documents hosted externally or generated by your backend, supporting dynamic receipts, invoices, or reports with real-time data.', }, ], }, + subSections: [ + { + type: 'Generic', + anchorLink: 'best-practices', + title: 'Best practices', + sectionContent: ` +- **Handle printing errors gracefully:** Implement proper error handling for print operations, including network failures, unsupported document types, or printer connectivity issues. +- **Optimize documents for printing:** Design your printable documents with appropriate sizing, margins, and formatting that work well with printers and standard paper sizes. +- **Provide user feedback:** Give users clear feedback about print operations, including loading states, success confirmations, and error messages when printing fails. +`, + }, + { + type: 'Generic', + anchorLink: 'limitations', + title: 'Limitations', + sectionContent: ` +- PDF printing on Android devices requires downloading the file and using an external application, which may interrupt the user workflow. +- Print operations depend on device printer connectivity and configuration, which may not be available in all POS setups. +- Document formatting and appearance may vary depending on the printer type, paper size, and device capabilities. +`, + }, + ], }; 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..9db71d20d6 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..0d759fd828 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..74c3f45592 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,81 @@ 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( - 'Receiving updates on available scanner sources', + '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( + '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: ` +- **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. +`, + }, + { + 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..d5b061ce4a 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\` and \`currency\` 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..05645b37ce 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/Badge.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/Badge.doc.ts index 2d7e4aec2e..79ce53f806 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,48 +7,51 @@ 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..c4056b5165 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,31 +7,50 @@ 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/Box.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/Box.doc.ts index 6533f630d3..ace1bd7b00 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/Box.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/Box.doc.ts @@ -7,23 +7,53 @@ const generateCodeBlockForBanner = (title: string, fileName: string) => const data: ReferenceEntityTemplateSchema = { name: 'Box', description: - 'A box component is a container that can be used to group and display content in a consistent manner.', + 'The `Box` component is a generic container that provides flexible layout with consistent spacing and styling. Use it to apply padding, to nest and group other components, or as the foundation for building structured layouts.\n\nThe component provides granular control over spacing through padding properties and sizing through width/height properties, serving as a building block for precise layouts. It simplifies the creation of containers with consistent spacing by using design system tokens, ensuring visual consistency and reducing the need for custom CSS in most layout scenarios.\n\n`Box` components provide shorthand properties for common padding patterns like equal padding on all sides or symmetric horizontal/vertical padding, reducing verbose property specifications for simpler layouts.', isVisualComponent: true, type: 'component', definitions: [ { - title: 'Box', - description: '', + title: 'Properties', + description: 'Configure the following properties on the `Box` component.', type: 'BoxProps', }, ], - category: 'Components', + category: 'UI components', + subCategory: 'Layout and structure', related: [], thumbnail: 'box-thumbnail.png', defaultExample: { image: 'box-default.png', - codeblock: generateCodeBlockForBanner('Box', 'default.example'), + codeblock: generateCodeBlockForBanner( + 'Create a container with padding', + 'default.example', + ), + description: + 'Create flexible layout containers with consistent spacing and styling. This example demonstrates a Box that applies padding, groups components, and provides granular control over spacing using design system tokens, serving as a foundation for structured layouts.', }, + subSections: [ + { + type: 'Generic', + anchorLink: 'best-practices', + title: 'Best practices', + sectionContent: ` +- **Apply consistent padding using the numeric scale:** Use the predefined numeric padding values (for example, \`'100'\`, \`'300'\`, \`'500'\`) to maintain consistency across your interface. Start with \`'300'\` for standard content and adjust up or down based on the visual hierarchy and spacing needs of your layout. +- **Use directional padding for precise control:** Use specific padding properties like \`paddingInline\` and \`paddingBlock\` when you need different spacing on different sides. This is particularly useful for creating asymmetric layouts or aligning content with other interface elements. +- **Combine Box with other layout components strategically:** Use \`Box\` as a foundation with other layout components like \`Stack\` for optimal results. \`Box\` handles spacing and sizing, while \`Stack\` manages the arrangement and alignment of child elements within the container. +- **Consider content flow and reading patterns:** When using directional properties, remember that \`block\` refers to the main content flow direction (usually vertical) and \`inline\` refers to the text direction (usually horizontal). +- **Optimize for touch interfaces:** Ensure adequate padding around interactive elements within \`Box\` containers. POS interfaces are primarily touch-based, so generous padding improves usability and reduces accidental interactions. Consider using padding values of \`'300'\` or higher for touch targets. +`, + }, + { + type: 'Generic', + anchorLink: 'limitations', + title: 'Limitations', + sectionContent: ` +- Box is a layout container and doesn't provide interactive functionality—use it in combination with interactive components like \`Button\` or \`Clickable\` for user interactions. +- Padding values are limited to the predefined numeric scale—custom pixel values for padding aren't supported to maintain design consistency. +- Box doesn't provide scrolling capabilities for overflow content—use \`ScrollView\` when content might exceed container dimensions. +`, + }, + ], }; export default data; 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..97472cd36e 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..a656b81915 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,81 +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..ab0fdbf7b9 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,30 +4,52 @@ 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.', }, subSections: [ { type: 'Generic', - anchorLink: 'guidelines', - title: 'Guidelines', + anchorLink: 'best-practices', + title: 'Best practices', sectionContent: ` -- Use a smart default date for common selections. - `, +- **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', 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..948acb6a91 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..d4d1850c7b 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,65 +7,53 @@ 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..ba0b0b4aa3 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 3ce3186291..aa2b9ff692 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: - 'This component is deprecated. Please use the [`TextField`](/docs/api/pos-ui-extensions/components/textfield) component instead. Use a formatted text field when you require additional functionality such as the text field input type or a custom validator.', + 'This component is deprecated. Use the [`TextField`](/docs/api/pos-ui-extensions/components/textfield) component instead. Use a formatted text field when you require additional functionality such as the text field input type or a custom validator.', 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 for an 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 6c958d7ada..4cc3b16097 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/shopify-pos-ui-kit', - 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..e6c64ed1bf 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,50 @@ 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: ` +- **Select the right fill behavior:** Use \`'contain'\` when showing the complete image is important, \`'cover'\` when filling the container is more important than showing the entire image, and \`'stretch'\` only when exact container filling is required regardless of distortion. +- **Optimize image sources:** Ensure image URLs are properly formatted, properly formatted, and optimized for web delivery. Consider image compression, appropriate file formats, and loading performance when selecting image sources. +- **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:** Choose size values that work well across different screen sizes and device orientations. 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 b749262eca..0c9e8a56d1 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..51205be6cd 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..5fe0e48419 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..46d6349dee 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..cf30c2e7b7 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/POSReceiptBlock.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/POSReceiptBlock.doc.ts index 0903d8db93..051c464ddb 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/POSReceiptBlock.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/POSReceiptBlock.doc.ts @@ -6,42 +6,48 @@ const generateCodeBlockForPOSReceiptBlock = (title: string, fileName: string) => const data: ReferenceEntityTemplateSchema = { name: 'POSReceiptBlock', - description: `A component used to group other components together for display on POS receipts. - > Note: - > This is part of a [POS UI Extensions developer preview](/docs/api/feature-previews#pos-ui-extensions-preview). More information to come. - > - > This component only accepts \`Text\` and \`QRCode\` components as children.`, + description: + 'The `POSReceiptBlock` component is part of the [POS UI extensions feature preview](/docs/api/feature-previews#pos-ui-extensions-preview). This feature preview is available on an invite-only basis and requires POS UI extensions version 2025-04 or 2025-07 and POS app version 9.31.0 or later.\n\nThe `POSReceiptBlock` component groups components together for display on POS receipts. Use it to display text and QR codes within receipt extensions, providing structured content for printed or digital receipts. The component handles 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-receipt-block-thumbnail.png', - category: 'Components', - related: [ - { - name: 'Text', - subtitle: 'Acceptable child components', - type: 'apps', - url: '/docs/api/pos-ui-extensions/components/text', - }, - { - name: 'QRCode', - subtitle: 'Acceptable child components', - type: 'apps', - url: '/docs/api/pos-ui-extensions/components/qrcode', - }, - { - name: 'pos.receipt-footer.block.render', - subtitle: 'Target', - type: 'blocks', - url: '/docs/api/pos-ui-extensions/targets/receipts/pos-receipt-footer-block-render', - }, - ], + category: 'UI components', + subCategory: 'Layout and structure', + related: [], defaultExample: { image: 'pos-receipt-block-default.png', codeblock: generateCodeBlockForPOSReceiptBlock( - 'Render a POSReceiptBlock in POS receipts', + 'Add content to a receipt', 'default.example', ), + description: + 'Display custom content on POS receipts using a structured block container. This example shows how to group text and QR codes within receipt extensions, providing structured content for printed or digital receipts with proper formatting and layout.', }, + subSections: [ + { + type: 'Generic', + anchorLink: 'best-practices', + title: 'Best practices', + sectionContent: ` +- **Optimize text for receipt formatting:** When using \`Text\` components within \`POSReceiptBlock\`, choose content and formatting that works well in receipt layouts. Keep text concise and ensure it remains readable when printed on receipt paper. +- **Design QR codes for easy scanning:** When including QR codes, ensure they encode useful information like store websites, feedback forms, or digital receipt access. Test QR code scanning in real-world conditions. +- **Consider both digital and print contexts:** Design your receipt block content to work effectively in both digital receipt displays and physical printed receipts. Ensure text remains legible and QR codes remain scannable across both formats. +- **Keep content focused and valuable:** Limit receipt block content to information that genuinely enhances the customer experience. Avoid cluttering receipts with excessive promotional content or information that isn't relevant to the transaction. +- **Maintain consistent receipt branding:** Use \`POSReceiptBlock\` consistently across your extension to create cohesive receipt experiences. Establish patterns for how you present information that customers can recognize and trust. +`, + }, + { + type: 'Generic', + anchorLink: 'limitations', + title: 'Limitations', + sectionContent: ` +- \`POSReceiptBlock\` only accepts \`Text\` and \`QRCode\` components as children—other component types aren't supported to ensure receipt formatting compatibility. +- The component is designed specifically for receipt contexts—it can't be used in other POS UI extension targets or general interface layouts. +- Content styling and layout are optimized for receipt formats—custom styling that might interfere with receipt printing or digital display is not supported. +- Interactive elements beyond QR codes aren't supported—receipts are primarily informational documents rather than interactive interfaces. +`, + }, + ], }; 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..d252d5000e 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,66 +29,31 @@ 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]. +- **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: 'guidelines', - title: 'Guidelines', + anchorLink: 'limitations', + title: 'Limitations', 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. - `, - }, - { - type: 'Generic', - anchorLink: 'content-guidelines', - title: 'Content guidelines', - 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/PrintPreview.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/PrintPreview.doc.ts index 6741ed1e78..d92e3106b5 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/PrintPreview.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/PrintPreview.doc.ts @@ -6,42 +6,56 @@ const generateCodeBlockForPrintPreview = (title: string, fileName: string) => const data: ReferenceEntityTemplateSchema = { name: 'PrintPreview', - description: ` - A component that displays a preview of a printable document. - > Note: - > This component must be a direct child of the Screen component and cannot be nested inside any other component.`, + description: + 'The `PrintPreview` component displays a preview of printable content from a specified source URL. Use it to show users what will be printed before triggering the actual print operation.\n\n`PrintPreview` works in conjunction with the Print API to provide complete print functionality from preview to execution.\n\nSupported document types:\n\n- **HTML documents** (`.html`, `.htm`) - Best printing experience with full CSS styling, embedded images, and complex layouts. Use for receipts, invoices, and formatted reports.\n\n- **Text files** (`.txt`, `.csv`) - Plain text with basic content and tabular data support. Use for simple receipts and data exports.\n\n- **Image files** (`.png`, `.jpg`, `.jpeg`, `.gif`, `.bmp`, `.webp`) - Common web formats with format-specific optimizations. Use for logos, charts, QR codes, and barcodes.\n\n- **PDF files** (`.pdf`) - Behavior varies by platform: prints directly on iOS/desktop, but downloads to external viewer on Android. Use for complex documents and compliance requirements.\n\n[Learn how to build a print extension in POS](/docs/apps/build/pos/build-print-extension).', isVisualComponent: true, type: 'component', thumbnail: 'print-preview-thumbnail.png', definitions: [ { - title: 'PrintPreview', + title: 'Properties', description: - 'Renders a preview of a printable document. This component must a direct child of the Screen component.', + 'Configure the following properties on the `PrintPreview` component. This component must be a direct child of the Screen component.', type: 'PrintPreviewProps', }, ], - category: 'Components', - related: [ - { - name: 'Print API', - subtitle: 'Handle print operations', - url: '/api/pos-ui-extensions/apis/print-api', - }, - { - name: 'Build a Print Extension', - subtitle: 'Learn how to implement printing', - url: '/docs/api/pos-ui-extensions/examples/print-extension', - }, - ], + category: 'UI components', + subCategory: 'Navigation and content', + related: [], defaultExample: { image: 'print-preview-default.png', - description: 'Basic usage with relative and full URLs:', codeblock: generateCodeBlockForPrintPreview( - 'Basic PrintPreview', + 'Preview printable content', 'default.example', ), + description: + 'Display a preview of printable content before triggering the print operation. This example shows how to use PrintPreview with HTML documents, PDFs, images, or text files, supporting various document formats with proper rendering for receipts, invoices, and formatted reports.', }, + subSections: [ + { + type: 'Generic', + anchorLink: 'best-practices', + title: 'Best practices', + sectionContent: ` +- **Design print-optimized content:** Structure your printable content with print-specific CSS media queries, appropriate page breaks, and formatting that works well on physical paper. Consider printer capabilities and paper sizes commonly used in POS environments. +- **Implement proper error handling:** Handle cases where the source URL is unavailable, the document format is unsupported, or network issues prevent content loading. Provide clear feedback to users when preview or printing fails. +- **Consider platform-specific limitations:** Be aware that PDF files on Android devices require external applications for printing. Design your workflow to handle this gracefully, potentially offering alternative formats or clear instructions for Android users. +- **Optimize source URL management:** Use relative paths when possible for internal app resources to simplify URL management and improve performance. Reserve full URLs for external resources or when you need complete control over the endpoint. +- **Provide clear print workflows:** Combine \`PrintPreview\` with appropriate UI controls like print buttons, allowing users to review content before committing to print. Consider implementing print confirmation dialogs for important or expensive print operations. +`, + }, + { + type: 'Generic', + anchorLink: 'limitations', + title: 'Limitations', + sectionContent: ` +- \`PrintPreview\` must be a direct child of the \`Screen\` component and can't be nested inside any other component—this structural requirement ensures proper preview rendering and print functionality. +- The component requires network access to fetch content from the specified source URL—offline functionality isn't supported for remote content. +- Content is displayed as-is from the source—real-time content modification or editing within the preview isn't supported. +- PDF printing on Android devices requires external applications—the component can't handle PDF printing natively on all platforms, which may affect user experience consistency across different POS devices. +`, + }, + ], }; export default data; diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/QRCode.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/QRCode.doc.ts index 00a8272dc6..b25f76c23d 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/QRCode.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/QRCode.doc.ts @@ -6,35 +6,54 @@ const generateCodeBlockForPOSReceiptBlock = (title: string, fileName: string) => const data: ReferenceEntityTemplateSchema = { name: 'QRCode', - description: `A component that renders a QR code in Shopify POS. - > Note: - > This is part of a [POS UI Extensions developer preview](/docs/api/feature-previews#pos-ui-extensions-preview). More information to come.`, + description: + 'The `QRCode` component renders a QR code for receipts in Shopify POS. Use QR codes to provide quick access to digital content, enable contactless interactions, or share information that customers and merchants can easily scan with mobile devices.\n\nThe component generates QR codes with customizable size and error correction levels, suitable for various use cases from customer-facing displays to inventory labels. It automatically handle encoding, scaling, and rendering optimizations to ensure reliable scanning across different lighting conditions and device cameras commonly found in retail environments.\n\nautomatically select appropriate error correction levels based on QR code content and intended display size, balancing scanability with data density for reliable reading across use cases.', requires: 'use within a `POSReceiptBlock` component', isVisualComponent: true, type: 'component', thumbnail: 'qrcode-thumbnail.png', definitions: [ { - title: 'QRCodeProps', - description: '', + title: 'Properties', + description: + 'Configure the following properties on the `QRCode` component.', type: 'QRCodeProps', }, ], - category: 'Components', - related: [ - { - name: 'POSReceiptBlock', - subtitle: 'Required parent wrapper component', - type: 'apps', - url: '/docs/api/pos-ui-extensions/components/posreceiptblock', - }, - ], + category: 'UI components', + subCategory: 'Media and visuals', + related: [], defaultExample: { codeblock: generateCodeBlockForPOSReceiptBlock( - 'Render a QRCode in POS receipts', + 'Display a QR code on a receipt', 'default.example', ), + description: + 'Render QR codes on receipts for quick access to digital content or contactless interactions. This example demonstrates generating QR codes with customizable size and error correction levels, enabling customers to easily scan information from printed or digital receipts.', }, + subSections: [ + { + type: 'Generic', + anchorLink: 'best-practices', + title: 'Best practices', + sectionContent: ` +- **Keep content concise and scannable:** QR codes become more complex and harder to scan with longer content. Keep encoded strings as short as possible while maintaining functionality. Use URL shorteners for long links or consider alternative approaches for extensive data. +- **Test QR code scannability:** Verify that generated QR codes scan correctly across different devices and QR code reader apps. Test in various lighting conditions and at different distances. +- **Provide context and instructions:** Include clear text near QR codes explaining what users can expect when they scan. For example, "Scan for store Wi-Fi access" or "Scan to view product details online." This helps users understand the value and builds confidence in scanning. +- **Consider placement and visibility:** Position QR codes where they're easily visible to customers. Ensure adequate contrast, appropriate sizing, and clear space around the code. Avoid placing QR codes in areas where they might be obscured or difficult to scan. +`, + }, + { + type: 'Generic', + anchorLink: 'limitations', + title: 'Limitations', + sectionContent: ` +- QR codes are display-only components and don't support click events or interactive behaviors—they rely on external scanning devices for interaction. +- QR code scanning depends on user devices and apps—not all users may have QR code scanning capabilities readily available. +- The \`QRCode\` component must be wrapped in a \`POSReceiptBlock\` component to be displayed on a receipt. +`, + }, + ], }; export default data; 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..93a01ae3b6 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..2256c4cf6a 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..22abece878 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\`, \`Section\`, or \`Box\` 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..7c75ad6fa9 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,56 +5,54 @@ 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..e09ee204c2 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..43b574fc10 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,54 @@ 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. +- **Maintain consistent header patterns:** Establish consistent patterns for how you use \`SectionHeader\` across your POS UI extension. Similar types of content should have similar header structures, helping users develop familiarity with your interface organization. +`, + }, + { + 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..9e4dbcfe1f 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..2c26b59b2b 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..400f2759cd 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 abeeb08acc..8a78cc18e8 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 @@ -21,151 +21,128 @@ 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. Stacks always wrap the content to the next column or row.', + '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', subSections: [ { type: 'Generic', - anchorLink: 'examples', - title: 'Examples', - sectionContent: ` -The following examples will demonstrate some, but not all of the abilities of the \`Stack\` component. For simplicity, these examples use the React version of the \`Stack\` component, but the same results will be achieved by using the same properties with the regular JS library. -`, - }, - { - type: 'Generic', - anchorLink: 'inline-default', - title: 'Inline Stack with default values', - sectionContent: ` -In this example, we specify \`inline\` for the \`direction\`. 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 \`justifyContent\` is set to \`start\` by default. We also include a \`gap\` of "200". -`, - codeblock: generateCodeBlockForStack( - 'Inline Stack with default values', - 'inline-default', - ), - image: 'extension-stack-inline.png', - }, - { - type: 'Generic', - anchorLink: 'inline-flex-children', - title: 'Inline 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 \`inline\` stack. - `, - codeblock: generateCodeBlockForStack( - 'Inline Stack with flexChildren', - 'inline-flex-children', - ), - image: 'extension-stack-inline-flexChildren.png', - }, - { - type: 'Generic', - anchorLink: 'inline-center-children', - title: 'Inline Stack with centered children', + anchorLink: 'best-practices', + title: 'Best practices', sectionContent: ` -You can also center elements in your \`inline\` stack. For this, you can specify the \`justifyContent\` 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. +- **Apply consistent spacing using the numeric scale:** Use the predefined numeric spacing values (for example, \`'100'\`, \`'300'\`, \`'500'\`) to maintain consistency across your interface. Start with \`'300'\` for standard spacing and adjust up or down based on your content hierarchy needs. +- **Use alignment properties for professional layouts:** Use the\`justifyContent\` property to control main axis distribution. Use \`alignItems\` for cross axis positioning of individual items, and \`alignContent\` for cross axis distribution when there's extra space. +- **Use gap properties for precise spacing control:** Take advantage of the flexible gap system - use \`gap\` for uniform spacing, \`rowGap\` for block axis control, and \`columnGap\` for inline axis control. +- **Combine with other layout components strategically:** Use the \`Stack\` component in combination with \`Box\` and \`Section\` components. Stack handles element arrangement and spacing, while other components provide additional layout capabilities. `, - codeblock: generateCodeBlockForStack( - 'Inline Stack with centered children', - 'inline-center-children', - ), - image: 'extension-stack-inline-centered.png', }, { type: 'Generic', - anchorLink: 'inline-align-items-center', - title: 'Inline Stack with vertical axis centering', - sectionContent: `Here we have an \`inline\` stack with two children. The first is a block stack with two buttons, and the second is a single button. Since the first element has a greater intrinsic height, our main inline stack's intrinsic height is also increased. We can center both children component along the main axis (x-axis) by setting the \`alignItems\` property to \`center\`.`, - codeblock: generateCodeBlockForStack( - 'Inline Stack with vertical axis centering', - 'inline-align-items-center', - ), - image: 'extension-stack-inline-align-items-center.png', - }, - { - type: 'Generic', - anchorLink: 'block', - title: 'Block Stack', - sectionContent: ` -You can specify your \`Stack\` to layout its children vertically by setting the \`direction\` property to \`block\`. - `, - codeblock: generateCodeBlockForStack('Block Stack', 'block'), - image: 'extension-stack-block.png', - }, - { - type: 'Generic', - anchorLink: 'extension-stack-block-space-between', - title: 'Block Stack with space between children', - sectionContent: ` - Here we are spacing out the children of our block stack by setting \`justifyContent\` to \`space-between\` in order to space the children out as much as possible along the vertical axis. Note that in this example, we removed the wrapping \`ScrollView\` in order to introduce a custom height by setting the \`blockSize\` to \`50%\`. We are also adding \`inlinePadding\` of \`450\` in order to mimic the padding applied to the UI Extension screen header. -`, - codeblock: generateCodeBlockForStack( - 'Block Stack with space between children', - 'block-space-between', - ), - image: 'extension-stack-block-space-between.png', - }, - { - type: 'Generic', - anchorLink: 'block-center-all', - title: 'Block Stack centered on both axes', + anchorLink: 'limitations', + title: 'Limitations', sectionContent: ` -You can center your block stack on the vertical axis by setting \`justifyContent\` to \`center\`. Next, you can set a custom size on your block stack by setting the \`blockSize\` and \`inlineSize\`. In this example we set them to \`50%\` and \`100%\` respectively. We can then center our elements along both axis of the stack by setting justifyContent to \`center\` to center the children vertically, and setting both \`alignContent\` and \`alignItems\` to \`center\`. +Wrapping behavior is determined by direction—inline stacks wrap content while block stacks don't, which may not suit all layout requirements. `, - codeblock: generateCodeBlockForStack( - 'Block Stack centered on both axes', - 'block-center-all', - ), - image: 'extension-stack-block-center-all.png', - }, - { - type: 'Generic', - anchorLink: 'block-align-content-stretch', - title: 'Block Stack with horizontal stretching', - sectionContent: ` -This example demonstrates a block stack with elements stretched to fill the width of the container. By setting \`alignContent\` to \`'stretch'\`, the children will expand to fill the available horizontal space. This is useful when you want all elements to have consistent width, regardless of their content. -`, - codeblock: generateCodeBlockForStack( - 'Block Stack with horizontally stretched contents', - 'block-align-content-stretch', - ), - image: 'extension-stack-block-align-content-stretch.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. The first stack is which we can refer to as the parent stack, is set to inline. It has two main children, a block stack on the left, and an inline stack on the right. To space them out completely along the horizontal axis, we set our parent inline stack's \`justifyContent\` to \`space-between\`. We also specify the \`inlineSize\` to be \`100%\` to take up the full width of the screen. - -The first child stack (the block stack) simply has a gap of 100 to space out the two \`Text\` components. - -The second child stack (the inline stack) has a gap of 600 to space out the \`Text\` and the \`Icon\`. We also set the \`alignItems\` and \`alignContent\` properties to \`center\` to center the \`Text\` and \`Icon\` within their stack. - -However, we also need to the \`alignItems\` and \`alignContent\` properties to \`center\` on the parent inline stack to center the two children stacks along the 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', }, ], - category: 'Components', - related: [], - thumbnail: 'stack-thumbnail.png', defaultExample: { image: 'stack-default.png', - codeblock: generateCodeBlockForStack('Stack', 'inline-default'), + codeblock: generateCodeBlockForStack( + 'Layout elements horizontally or vertically', + 'inline-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', + 'block', + ), + 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-block.png', + }, + { + codeblock: generateCodeBlockForStack( + 'Center content on both axes', + 'block-center-all', + ), + 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-block-center-all.png', + }, + { + codeblock: generateCodeBlockForStack( + 'Center elements horizontally', + 'inline-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-inline-centered.png', + }, + { + codeblock: generateCodeBlockForStack( + 'Center elements vertically', + 'inline-align-items-center', + ), + description: + 'Center children along the vertical axis using `alignItems="center"`. This example shows an inline stack with two children of different heights (a nested block stack and a button)—since the block stack has greater intrinsic height, `alignItems="center"` centers both children along the cross-axis.', + image: 'extension-stack-inline-align-items-center.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( + 'Expand children to fill available space', + 'inline-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-inline-flexChildren.png', + }, + { + codeblock: generateCodeBlockForStack( + 'Space elements apart vertically', + 'block-space-between', + ), + 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-block-space-between.png', + }, + { + codeblock: generateCodeBlockForStack( + 'Stretch elements horizontally', + 'block-align-content-stretch', + ), + description: + 'Stretch child elements to fill container width using `alignContent="stretch"`. This makes all children expand horizontally to fill available space regardless of content, ensuring consistent full-width elements in vertical layouts.', + image: 'extension-stack-block-align-content-stretch.png', + }, + ], }, }; 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..ae708a3f6a 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 ec1c2e624d..6119ec06e8 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. By default, `Text` will always stretch to fill the width of the container, but it can be wrapped in a `Box` to limit its width to what it needs. When the width of `Text` reaches its limit, the `string` will automatically wrap to the next line.', + '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..33edc01681 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..4ff35ab747 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,37 +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: 'limitations', + title: 'Limitations', + sectionContent: ` +- \`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. +`, }, { type: 'Generic', 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..2b7278f9ac 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..1e3f4f6701 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,30 +4,52 @@ 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.', }, 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', 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..91c1bf120f 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/examples/targets/pos-cart-update-event-observe.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/examples/targets/pos-cart-update-event-observe.ts new file mode 100644 index 0000000000..4c52c89e7e --- /dev/null +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/examples/targets/pos-cart-update-event-observe.ts @@ -0,0 +1,22 @@ +import {eventExtension} from '@shopify/ui-extensions/point-of-sale'; + +export default eventExtension('pos.cart-update.event.observe', (eventData) => { + // Access cart data from the event + const {cart} = eventData; + + // Log cart changes for analytics or trigger workflows + console.log('Cart updated:', { + lineItemCount: cart.lineItems.length, + grandTotal: cart.grandTotal, + hasCustomer: !!cart.customer, + }); + + // Example: Trigger a workflow based on cart contents + if (cart.lineItems.length > 5) { + console.log('Large cart detected - consider bulk discount'); + } + + // Return success (no errors) + return {}; +}); + diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/examples/targets/pos-cart-update-event-observe.tsx b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/examples/targets/pos-cart-update-event-observe.tsx new file mode 100644 index 0000000000..1bfc4b2d69 --- /dev/null +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/examples/targets/pos-cart-update-event-observe.tsx @@ -0,0 +1,25 @@ +import {reactEventExtension} from '@shopify/ui-extensions-react/point-of-sale'; + +export default reactEventExtension( + 'pos.cart-update.event.observe', + (eventData) => { + // Access cart data from the event + const {cart} = eventData; + + // Log cart changes for analytics or trigger workflows + console.log('Cart updated:', { + lineItemCount: cart.lineItems.length, + grandTotal: cart.grandTotal, + hasCustomer: !!cart.customer, + }); + + // Example: Trigger a workflow based on cart contents + if (cart.lineItems.length > 5) { + console.log('Large cart detected - consider bulk discount'); + } + + // Return success (no errors) + return {}; + }, +); + diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/examples/targets/pos-cash-tracking-session-complete-event-observe.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/examples/targets/pos-cash-tracking-session-complete-event-observe.ts new file mode 100644 index 0000000000..88d2ad32b4 --- /dev/null +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/examples/targets/pos-cash-tracking-session-complete-event-observe.ts @@ -0,0 +1,30 @@ +import {eventExtension} from '@shopify/ui-extensions/point-of-sale'; + +export default eventExtension( + 'pos.cash-tracking-session-complete.event.observe', + (eventData) => { + // Access session data from the event + const {cashTrackingSessionComplete} = eventData; + + // Log session completion for audit trails + console.log('Cash tracking session completed:', { + sessionId: cashTrackingSessionComplete.id, + openingTime: new Date(cashTrackingSessionComplete.openingTime).toISOString(), + closingTime: new Date(cashTrackingSessionComplete.closingTime).toISOString(), + }); + + // Example: Generate end-of-shift report + // fetch('/api/cash-sessions/complete', { + // method: 'POST', + // body: JSON.stringify({ + // sessionId: cashTrackingSessionComplete.id, + // openingTime: cashTrackingSessionComplete.openingTime, + // closingTime: cashTrackingSessionComplete.closingTime, + // }), + // }); + + // Return success (no errors) + return {}; + }, +); + diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/examples/targets/pos-cash-tracking-session-complete-event-observe.tsx b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/examples/targets/pos-cash-tracking-session-complete-event-observe.tsx new file mode 100644 index 0000000000..4854571b17 --- /dev/null +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/examples/targets/pos-cash-tracking-session-complete-event-observe.tsx @@ -0,0 +1,30 @@ +import {reactEventExtension} from '@shopify/ui-extensions-react/point-of-sale'; + +export default reactEventExtension( + 'pos.cash-tracking-session-complete.event.observe', + (eventData) => { + // Access session data from the event + const {cashTrackingSessionComplete} = eventData; + + // Log session completion for audit trails + console.log('Cash tracking session completed:', { + sessionId: cashTrackingSessionComplete.id, + openingTime: new Date(cashTrackingSessionComplete.openingTime).toISOString(), + closingTime: new Date(cashTrackingSessionComplete.closingTime).toISOString(), + }); + + // Example: Generate end-of-shift report + // fetch('/api/cash-sessions/complete', { + // method: 'POST', + // body: JSON.stringify({ + // sessionId: cashTrackingSessionComplete.id, + // openingTime: cashTrackingSessionComplete.openingTime, + // closingTime: cashTrackingSessionComplete.closingTime, + // }), + // }); + + // Return success (no errors) + return {}; + }, +); + diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/examples/targets/pos-cash-tracking-session-start-event-observe.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/examples/targets/pos-cash-tracking-session-start-event-observe.ts new file mode 100644 index 0000000000..c0be43ec4f --- /dev/null +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/examples/targets/pos-cash-tracking-session-start-event-observe.ts @@ -0,0 +1,28 @@ +import {eventExtension} from '@shopify/ui-extensions/point-of-sale'; + +export default eventExtension( + 'pos.cash-tracking-session-start.event.observe', + (eventData) => { + // Access session data from the event + const {cashTrackingSessionStart} = eventData; + + // Log session start for compliance or security + console.log('Cash tracking session started:', { + sessionId: cashTrackingSessionStart.id, + openingTime: new Date(cashTrackingSessionStart.openingTime).toISOString(), + }); + + // Example: Send session start notification to backend + // fetch('/api/cash-sessions/start', { + // method: 'POST', + // body: JSON.stringify({ + // sessionId: cashTrackingSessionStart.id, + // openingTime: cashTrackingSessionStart.openingTime, + // }), + // }); + + // Return success (no errors) + return {}; + }, +); + diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/examples/targets/pos-cash-tracking-session-start-event-observe.tsx b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/examples/targets/pos-cash-tracking-session-start-event-observe.tsx new file mode 100644 index 0000000000..7d62e9a847 --- /dev/null +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/examples/targets/pos-cash-tracking-session-start-event-observe.tsx @@ -0,0 +1,28 @@ +import {reactEventExtension} from '@shopify/ui-extensions-react/point-of-sale'; + +export default reactEventExtension( + 'pos.cash-tracking-session-start.event.observe', + (eventData) => { + // Access session data from the event + const {cashTrackingSessionStart} = eventData; + + // Log session start for compliance or security + console.log('Cash tracking session started:', { + sessionId: cashTrackingSessionStart.id, + openingTime: new Date(cashTrackingSessionStart.openingTime).toISOString(), + }); + + // Example: Send session start notification to backend + // fetch('/api/cash-sessions/start', { + // method: 'POST', + // body: JSON.stringify({ + // sessionId: cashTrackingSessionStart.id, + // openingTime: cashTrackingSessionStart.openingTime, + // }), + // }); + + // Return success (no errors) + return {}; + }, +); + diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/examples/targets/pos-transaction-complete-event-observe.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/examples/targets/pos-transaction-complete-event-observe.ts new file mode 100644 index 0000000000..b7c6d04133 --- /dev/null +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/examples/targets/pos-transaction-complete-event-observe.ts @@ -0,0 +1,38 @@ +import {eventExtension} from '@shopify/ui-extensions/point-of-sale'; + +export default eventExtension( + 'pos.transaction-complete.event.observe', + (eventData) => { + // Access transaction data from the event + const {transaction} = eventData; + + // Log completed transaction for analytics + console.log('Transaction completed:', { + type: transaction.transactionType, + grandTotal: transaction.grandTotal.amount, + itemCount: transaction.lineItems?.length || 0, + hasCustomer: !!transaction.customer, + executedAt: transaction.executedAt, + }); + + // Example: Trigger post-transaction workflow + if (transaction.transactionType === 'Sale' && transaction.grandTotal.amount > 100) { + console.log('High-value sale - send thank you email'); + } + + // Example: Update external analytics system + // fetch('/api/analytics/transaction', { + // method: 'POST', + // body: JSON.stringify({ + // transactionType: transaction.transactionType, + // grandTotal: transaction.grandTotal, + // lineItems: transaction.lineItems, + // executedAt: transaction.executedAt, + // }), + // }); + + // Return success (no errors) + return {}; + }, +); + diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/examples/targets/pos-transaction-complete-event-observe.tsx b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/examples/targets/pos-transaction-complete-event-observe.tsx new file mode 100644 index 0000000000..625b38cbf0 --- /dev/null +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/examples/targets/pos-transaction-complete-event-observe.tsx @@ -0,0 +1,38 @@ +import {reactEventExtension} from '@shopify/ui-extensions-react/point-of-sale'; + +export default reactEventExtension( + 'pos.transaction-complete.event.observe', + (eventData) => { + // Access transaction data from the event + const {transaction} = eventData; + + // Log completed transaction for analytics + console.log('Transaction completed:', { + type: transaction.transactionType, + grandTotal: transaction.grandTotal.amount, + itemCount: transaction.lineItems?.length || 0, + hasCustomer: !!transaction.customer, + executedAt: transaction.executedAt, + }); + + // Example: Trigger post-transaction workflow + if (transaction.transactionType === 'Sale' && transaction.grandTotal.amount > 100) { + console.log('High-value sale - send thank you email'); + } + + // Example: Update external analytics system + // fetch('/api/analytics/transaction', { + // method: 'POST', + // body: JSON.stringify({ + // transactionType: transaction.transactionType, + // grandTotal: transaction.grandTotal, + // lineItems: transaction.lineItems, + // executedAt: transaction.executedAt, + // }), + // }); + + // Return success (no errors) + return {}; + }, +); + diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.cart-update.event.observe.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.cart-update.event.observe.doc.ts index 945f267fc0..a668071a63 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.cart-update.event.observe.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.cart-update.event.observe.doc.ts @@ -1,18 +1,28 @@ import type {ReferenceEntityTemplateSchema} from '@shopify/generate-docs'; +import {generateCodeBlock} from '../helpers/generateCodeBlock'; import {CUSTOM_DATA} from '../helpers/helper.docs'; import {ExtensionTargetType} from '../types/ExtensionTargetType'; const data: ReferenceEntityTemplateSchema = { name: ExtensionTargetType.PosCartUpdateObserve, - description: `An event extension target that observes cart updates - > Note: - > This is part of a [POS UI Extensions developer preview](/docs/api/feature-previews#pos-ui-extensions-preview). More information to come.`, + description: + 'Observes cart updates during active transactions, triggering whenever merchants add, remove, or modify line items. Use this target for real-time responses to cart changes like dynamic pricing, inventory validation, or promotional offer applications based on current cart contents.' + + '\n\nExtensions at this target receive complete cart data including line items, totals, discounts, and customer information whenever the cart state changes.', category: 'Targets', subCategory: 'Cart details', isVisualComponent: false, related: [], type: 'Target', definitions: [CUSTOM_DATA('CartUpdateEventData')], + defaultExample: { + codeblock: generateCodeBlock( + 'Monitor cart changes in real time', + 'targets', + 'pos-cart-update-event-observe', + ), + description: + 'Subscribe to cart update events to respond to cart modifications automatically. This example demonstrates tracking cart changes for analytics, triggering workflows based on cart contents, or implementing dynamic pricing rules that react to line item additions or removals.', + }, }; export default data; diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.cash-tracking-session-complete.event.observe.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.cash-tracking-session-complete.event.observe.doc.ts index 21e240a793..ef66260246 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.cash-tracking-session-complete.event.observe.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.cash-tracking-session-complete.event.observe.doc.ts @@ -1,25 +1,28 @@ import type {ReferenceEntityTemplateSchema} from '@shopify/generate-docs'; +import {generateCodeBlock} from '../helpers/generateCodeBlock'; import {CUSTOM_DATA} from '../helpers/helper.docs'; import {ExtensionTargetType} from '../types/ExtensionTargetType'; const data: ReferenceEntityTemplateSchema = { name: ExtensionTargetType.PosCashTrackingSessionCompleteObserve, - description: `An event extension target that observes when cash tracking session completes - > Note: - > This is part of a [POS UI Extensions developer preview](/docs/api/feature-previews#pos-ui-extensions-preview). More information to come.`, + description: + 'Observes when cash tracking sessions complete, triggering when merchants finish cash handling operations. Use this target for monitoring cash handling completion for audit trails, compliance reporting, or operational analytics.' + + '\n\nExtensions at this target receive session data including the session ID, opening time, and closing time when a cash tracking session is completed.', category: 'Targets', subCategory: 'Cash tracking', isVisualComponent: false, - related: [ - { - name: ExtensionTargetType.PosCashTrackingSessionStartObserve, - subtitle: 'Target', - type: 'blocks', - url: '/docs/api/pos-ui-extensions/targets/cash-tracking/pos-cash-tracking-session-start-observe', - }, - ], + related: [], type: 'Target', definitions: [CUSTOM_DATA('CashTrackingSessionCompleteData')], + defaultExample: { + codeblock: generateCodeBlock( + 'Track cash session closures', + 'targets', + 'pos-cash-tracking-session-complete-event-observe', + ), + description: + 'Subscribe to cash tracking session completion events to generate end-of-shift reports and reconcile cash handling. This example demonstrates logging session closures with session ID, opening time, and closing time, enabling audit trails, compliance notifications, and comprehensive cash management tracking.', + }, }; export default data; diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.cash-tracking-session-start.event.observe.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.cash-tracking-session-start.event.observe.doc.ts index 9afaf6bc55..8863ba7893 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.cash-tracking-session-start.event.observe.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.cash-tracking-session-start.event.observe.doc.ts @@ -5,22 +5,24 @@ import {ExtensionTargetType} from '../types/ExtensionTargetType'; const data: ReferenceEntityTemplateSchema = { name: ExtensionTargetType.PosCashTrackingSessionStartObserve, - description: `An event extension target that observes when cash tracking session starts - > Note: - > This is part of a [POS UI Extensions developer preview](/docs/api/feature-previews#pos-ui-extensions-preview). More information to come.`, + description: + 'Observes when cash tracking sessions begin, triggering when merchants start cash handling operations. Use this target for monitoring cash handling activities for compliance, security, or operational reporting purposes.' + + '\n\nExtensions at this target receive session data including the session ID and opening time when a new cash tracking session is initiated.', category: 'Targets', subCategory: 'Cash tracking', isVisualComponent: false, - related: [ - { - name: ExtensionTargetType.PosCashTrackingSessionCompleteObserve, - subtitle: 'Target', - type: 'blocks', - url: '/docs/api/pos-ui-extensions/targets/cash-tracking/pos-cash-tracking-session-complete-observe', - }, - ], + related: [], type: 'Target', definitions: [CUSTOM_DATA('CashTrackingSessionStartData')], + defaultExample: { + codeblock: generateCodeBlock( + 'Track cash session openings', + 'targets', + 'pos-cash-tracking-session-start-event-observe', + ), + description: + 'Subscribe to cash tracking session start events to maintain audit trails and compliance records. This example demonstrates logging session openings with session ID and opening time, enabling security monitoring, compliance reporting, and integration with external cash management systems.', + }, }; 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..1969a41c58 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', 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..0a9539032a 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', 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/docs/surfaces/point-of-sale/reference/targets/pos.receipt-footer.block.render.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.receipt-footer.block.render.doc.ts index 18fccc9a94..557ed60d47 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.receipt-footer.block.render.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.receipt-footer.block.render.doc.ts @@ -5,27 +5,22 @@ import {ExtensionTargetType} from '../types/ExtensionTargetType'; const data: ReferenceEntityTemplateSchema = { name: ExtensionTargetType.PosReceiptFooterBlockRender, - description: `Renders a custom section within the POS receipt footer - > Note: - > This is part of a [POS UI Extensions developer preview](/docs/api/feature-previews#pos-ui-extensions-preview). More information to come.`, + description: + 'Renders a custom section in the footer of printed receipts. Use this target for adding contact details, return policies, social media links, or customer engagement elements like survey links or marketing campaigns at the bottom of receipts.' + + '\n\nExtensions at this target appear in the receipt footer area and support limited components optimized for print formatting, including text content for information display.', defaultExample: { codeblock: generateCodeBlock( - 'Block', + 'Add content to receipt footer', 'targets', 'pos-receipt-footer-block-render', ), + description: + 'Display custom content in the footer of printed receipts. This example shows how to create a footer section with contact details, return policies, social media links, or customer engagement elements like survey links, providing additional context and marketing opportunities on receipts.', }, category: 'Targets', subCategory: 'Receipts', isVisualComponent: false, - related: [ - { - name: 'POSReceiptBlock', - subtitle: 'Component', - type: 'apps', - url: '/docs/api/pos-ui-extensions/components/posreceiptblock', - }, - ], + related: [], type: 'Target', ...TRANSACTION_COMPLETE_DEFINITION, }; diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.transaction-complete.event.observe.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.transaction-complete.event.observe.doc.ts index c8ca9d3863..36a872c63c 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.transaction-complete.event.observe.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.transaction-complete.event.observe.doc.ts @@ -1,31 +1,28 @@ import type {ReferenceEntityTemplateSchema} from '@shopify/generate-docs'; +import {generateCodeBlock} from '../helpers/generateCodeBlock'; import {TRANSACTION_COMPLETE_DEFINITION} from '../helpers/helper.docs'; import {ExtensionTargetType} from '../types/ExtensionTargetType'; const data: ReferenceEntityTemplateSchema = { name: ExtensionTargetType.PosTransactionCompleteObserve, - description: `An event extension target that observes completed transactions - > Note: - > This is part of a [POS UI Extensions developer preview](/docs/api/feature-previews#pos-ui-extensions-preview). More information to come.`, + description: + 'Observes completed transactions including sales, returns, and exchanges, triggering when transactions are finalized. Use this target for post-transaction processing, analytics collection, and automated workflows that need to respond to completed sales activities.' + + '\n\nExtensions at this target receive detailed transaction information including transaction type, totals, line items, and customer data when any transaction type is completed.', category: 'Targets', subCategory: 'Post-purchase', isVisualComponent: false, - related: [ - { - name: 'pos.receipt-footer.block.render', - subtitle: 'Target', - type: 'blocks', - url: '/docs/api/pos-ui-extensions/targets/receipts/pos-receipt-footer-block-render', - }, - { - name: 'POSReceiptBlock', - subtitle: 'Component', - type: 'apps', - url: '/docs/api/pos-ui-extensions/components/posreceiptblock', - }, - ], + related: [], type: 'Target', ...TRANSACTION_COMPLETE_DEFINITION, + defaultExample: { + codeblock: generateCodeBlock( + 'Process completed transactions', + 'targets', + 'pos-transaction-complete-event-observe', + ), + description: + 'Subscribe to transaction completion events to trigger post-sale workflows and analytics. This example demonstrates capturing completed sales, returns, and exchanges with detailed transaction data, enabling automated workflows like sending digital receipts, updating external systems, or collecting sales analytics.', + }, }; export default data; diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/event/data/BaseData.ts b/packages/ui-extensions/src/surfaces/point-of-sale/event/data/BaseData.ts index f6e28e10aa..3a099d9b34 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/event/data/BaseData.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/event/data/BaseData.ts @@ -1,8 +1,23 @@ import type {ConnectivityState, Device, Session} from '../../../point-of-sale'; +/** + * Base data object provided to all extension targets containing device information, session context, and connectivity state. This data is available at extension initialization and provides essential context about the runtime environment. + */ export interface BaseData { + /** + * The current Internet connectivity state of the POS device. Indicates whether the device is connected to or disconnected from the Internet. This state updates in real-time as connectivity changes, allowing extensions to adapt behavior for offline scenarios, show connectivity warnings, or queue operations for when connectivity is restored. + */ connectivity: ConnectivityState; + /** + * Comprehensive information about the physical POS device where the extension is currently running. Includes the device name, unique device ID, and form factor information (tablet vs other). This data is static for the session and helps extensions adapt to different device types, log device-specific information, or implement device-based configurations. + */ device: Device; + /** + * The [IETF BCP 47](https://en.wikipedia.org/wiki/IETF_language_tag) locale string for the current POS session (for example, `"en-US"`, `"fr-CA"`, `"de-DE"`). This indicates the merchant's language and regional preferences. Commonly used for internationalization (i18n), locale-specific date/time/number formatting, translating UI text, and providing localized content. The locale remains constant for the session and reflects the language selected in POS settings. + */ locale: string; + /** + * Comprehensive information about the current POS session including shop ID and domain, authenticated user, pinned staff member, active location, currency settings, and POS version. This session data remains constant for the session duration and provides critical context for business logic, permissions, API authentication, and transaction processing. Session data updates when users switch locations or change pinned staff members. + */ session: Session; } diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/event/data/CartUpdateEventData.ts b/packages/ui-extensions/src/surfaces/point-of-sale/event/data/CartUpdateEventData.ts index 1c93817926..936bfecb18 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/event/data/CartUpdateEventData.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/event/data/CartUpdateEventData.ts @@ -1,6 +1,12 @@ import {BaseData} from './BaseData'; import {Cart} from '../../api'; +/** + * The data object provided to cart update extension targets. Contains the current cart state along with device, session, and connectivity information. This data is passed to extensions whenever the cart changes, enabling real-time cart monitoring and cart-based business logic. + */ export interface CartUpdateEventData extends BaseData { + /** + * The complete current `Cart` object containing all cart data including line items with products and quantities, pricing totals (subtotal, tax, grand total), associated customer information, applied discounts, custom properties, and editability state. This represents the cart's state at the moment the extension is triggered, reflecting all recent changes. The cart object is read-only in this context—modifications should be made through the Cart API methods. + */ cart: Cart; } diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/event/data/CashTrackingSessionData.ts b/packages/ui-extensions/src/surfaces/point-of-sale/event/data/CashTrackingSessionData.ts index cde5e9042d..adf97e729d 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/event/data/CashTrackingSessionData.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/event/data/CashTrackingSessionData.ts @@ -1,16 +1,43 @@ import {BaseData} from './BaseData'; +/** + * The data object provided to cash tracking session start extension targets. Contains information about a newly opened cash tracking session along with device and session context. + */ export interface CashTrackingSessionStartData extends BaseData { + /** + * The cash tracking session start data containing the session identifier and the time when the session began. Cash tracking sessions represent the period during which a cash drawer is open and being used for transactions, typically corresponding to a staff member's shift. + */ cashTrackingSessionStart: { + /** + * The unique numeric identifier for this cash tracking session. This ID matches the ID from when the session was opened and can be used to correlate session start and end events, retrieve session-specific data, or link all transactions that occurred during this session. + */ id: number; + /** + * The [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp when the cash tracking session was opened and began (for example, `"2024-05-15T09:00:00Z"`). This marks the start of the session and can be compared with `closingTime` to calculate the total session duration or shift length. + */ openingTime: string; }; } +/** + * The data object provided to cash tracking session complete extension targets. Contains information about a completed cash tracking session including when it opened and closed, along with device and session context. + */ export interface CashTrackingSessionCompleteData extends BaseData { + /** + * The cash tracking session complete data containing the session identifier, opening time, and closing time. This represents the full lifecycle of a cash drawer session from opening to closing. + */ cashTrackingSessionComplete: { + /** + * The unique numeric identifier for this cash tracking session. This ID matches the ID from when the session was opened and can be used to correlate session start and end events, retrieve session-specific data, or link all transactions that occurred during this session. + */ id: number; + /** + * The [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp when the cash tracking session was opened and began (for example, `"2024-05-15T09:00:00Z"`). This marks the start of the session and can be compared with `closingTime` to calculate the total session duration or shift length. + */ openingTime: string; + /** + * The [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp when the cash tracking session was closed and ended (for example, `"2024-05-15T17:30:00Z"`). This marks when the staff member completed their shift, closed out the cash drawer, and finalized the session. The time between `openingTime` and `closingTime` represents the active session duration. Commonly used for shift reporting, calculating hours worked, or determining the timeframe for session-specific transactions. + */ closingTime: string; }; } diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/event/data/ExchangeTransactionData.ts b/packages/ui-extensions/src/surfaces/point-of-sale/event/data/ExchangeTransactionData.ts index 172e484d56..f9a45d39fd 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/event/data/ExchangeTransactionData.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/event/data/ExchangeTransactionData.ts @@ -1,9 +1,28 @@ import {BaseTransactionComplete} from '../../types/base-transaction-complete'; import {LineItem} from '../../types/cart'; +/** + * Defines the data structure for completed exchange transactions. + */ export interface ExchangeTransactionData extends BaseTransactionComplete { + /** + * The transaction type identifier, always 'Sale' for sale transactions. + */ transactionType: 'Exchange'; + /** + * The return ID for the completed return transaction. + */ + returnId?: number; + /** + * The exchange ID if the return is part of an exchange transaction. + */ exchangeId?: number; + /** + * An array of line items added to the customer in the exchange. + */ lineItemsAdded: LineItem[]; + /** + * An array of line items removed from the customer in the exchange. + */ lineItemsRemoved: LineItem[]; } diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/event/data/ReprintReceiptData.ts b/packages/ui-extensions/src/surfaces/point-of-sale/event/data/ReprintReceiptData.ts index 437a25082b..47e311fd2d 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/event/data/ReprintReceiptData.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/event/data/ReprintReceiptData.ts @@ -1,7 +1,16 @@ import {BaseTransactionComplete} from '../../types/base-transaction-complete'; import {LineItem} from '../../types/cart'; +/** + * Defines the data structure for receipt reprint requests. + */ export interface ReprintReceiptData extends BaseTransactionComplete { + /** + * The transaction type identifier, always 'Sale' for sale transactions. + */ transactionType: 'Reprint'; + /** + * An array of line items included in the sale transaction. + */ lineItems: LineItem[]; } diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/event/data/ReturnTransactionData.ts b/packages/ui-extensions/src/surfaces/point-of-sale/event/data/ReturnTransactionData.ts index d8472853e3..3f2f224408 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/event/data/ReturnTransactionData.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/event/data/ReturnTransactionData.ts @@ -1,7 +1,28 @@ import {BaseTransactionComplete} from '../../types/base-transaction-complete'; import {LineItem} from '../../types/cart'; +/** + * Defines the data structure for completed return transactions. + */ export interface ReturnTransactionData extends BaseTransactionComplete { + /** + * The transaction type identifier, always 'Sale' for sale transactions. + */ transactionType: 'Return'; + /** + * The refund ID if a refund was issued for the return. + */ + refundId?: number; + /** + * The return ID for the completed return transaction. + */ + returnId?: number; + /** + * The exchange ID if the return is part of an exchange transaction. + */ + exchangeId?: number; + /** + * An array of line items included in the sale transaction. + */ lineItems: LineItem[]; } diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/event/data/SaleTransactionData.ts b/packages/ui-extensions/src/surfaces/point-of-sale/event/data/SaleTransactionData.ts index afb11d6e93..72df0e358c 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/event/data/SaleTransactionData.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/event/data/SaleTransactionData.ts @@ -1,8 +1,20 @@ import {BaseTransactionComplete} from '../../types/base-transaction-complete'; import {LineItem} from '../../types/cart'; +/** + * Defines the data structure for completed sale transactions. + */ export interface SaleTransactionData extends BaseTransactionComplete { + /** + * The transaction type identifier, always 'Sale' for sale transactions. + */ transactionType: 'Sale'; + /** + * The UUID of the draft checkout if the sale originated from a draft order. + */ draftCheckoutUuid?: string; + /** + * An array of line items included in the sale transaction. + */ lineItems: LineItem[]; } diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/event/data/TransactionCompleteData.ts b/packages/ui-extensions/src/surfaces/point-of-sale/event/data/TransactionCompleteData.ts index 44f8c7dd77..b4179b1461 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/event/data/TransactionCompleteData.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/event/data/TransactionCompleteData.ts @@ -2,10 +2,38 @@ import {BaseData} from './BaseData'; import type {SaleTransactionData} from './SaleTransactionData'; import type {ExchangeTransactionData} from './ExchangeTransactionData'; import type {ReturnTransactionData} from './ReturnTransactionData'; +import type {ReprintReceiptData} from './ReprintReceiptData'; +/** + * The data object provided to receipt targets containing transaction details. + */ export interface TransactionCompleteData extends BaseData { + /** + * The transaction data, which can be one of the following types: + * - `SaleTransactionData`: Defines the data structure for completed sale transactions. + * - `ReturnTransactionData`: Defines the data structure for completed return transactions. + * - `ExchangeTransactionData`: Defines the data structure for completed exchange transactions. + */ transaction: | SaleTransactionData | ReturnTransactionData | ExchangeTransactionData; } + +/** + * The data object provided to receipt targets containing transaction details and reprint information. + */ +export interface TransactionCompleteWithReprintData extends BaseData { + /** + * The transaction data, which can be one of the following types: + * - `SaleTransactionData`: Defines the data structure for completed sale transactions. + * - `ReturnTransactionData`: Defines the data structure for completed return transactions. + * - `ExchangeTransactionData`: Defines the data structure for completed exchange transactions. + * - `ReprintReceiptData`: Defines the data structure for receipt reprint requests. + */ + transaction: + | SaleTransactionData + | ReturnTransactionData + | ExchangeTransactionData + | ReprintReceiptData; +} diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/event/output/BaseOutput.ts b/packages/ui-extensions/src/surfaces/point-of-sale/event/output/BaseOutput.ts index 9838043833..b92bbf8462 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/event/output/BaseOutput.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/event/output/BaseOutput.ts @@ -1,8 +1,22 @@ interface ExtensionError extends Error { + /** + * The severity level of this error: + * - `'error'`: A critical error that prevents the extension from completing successfully. Errors typically block the user workflow and require resolution before proceeding. + * - `'warning'`: A non-critical issue that doesn't prevent extension execution but indicates a problem or unexpected condition. Warnings allow the workflow to continue but should be logged or displayed to users. + */ level: 'error' | 'warning'; + /** + * The human-readable error message describing what went wrong. This message should be clear and actionable, helping merchants understand the issue and how to resolve it (for example, "Product not found", "Invalid discount code", "Insufficient inventory"). The message may be displayed to users in the POS interface depending on the error severity and context. + */ message: string; } +/** + * Base output structure that extensions can return to communicate errors and warnings back to the POS system. Extensions populate this interface when they encounter issues during execution. + */ export interface BaseOutput { + /** + * An array of errors or warnings encountered during extension execution. Each error includes a severity level (`'error'` or `'warning'`) and a descriptive message. Multiple errors can be reported simultaneously. Returns `undefined` or empty array when the extension executes successfully without issues. Critical errors may prevent transaction completion, while warnings allow the transaction to proceed but indicate issues that should be addressed. + */ errors?: ExtensionError[]; } diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/render/api/action-api/action-api.ts b/packages/ui-extensions/src/surfaces/point-of-sale/render/api/action-api/action-api.ts index 800bb8c319..174c9269c3 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/render/api/action-api/action-api.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/render/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/render/api/cart-api/cart-api.ts b/packages/ui-extensions/src/surfaces/point-of-sale/render/api/cart-api/cart-api.ts index 552f096031..50e38778d6 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/render/api/cart-api/cart-api.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/render/api/cart-api/cart-api.ts @@ -10,31 +10,39 @@ 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; } +/** + * 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; - /** Bulk update the cart + /** + * Perform a bulk update of the entire cart state including note, discounts, customer, line items, and properties. Returns the updated cart object after the operation completes with enhanced validation and error handling. + * * @param cartState the cart state to set * @returns the updated cart */ bulkCartUpdate(cartState: CartUpdateInput): Promise; - /** 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. @@ -45,59 +53,84 @@ 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 with improved error messaging. + * * @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 does not 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 with enhanced discount allocation handling. + * * @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 enhanced 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. Returns the `UUID` of the created line item for future operations and property management. + * * @param customSale the custom sale object to add to the cart - * @returns {string} the uuid of the line item added + * @returns {string} the UUID of the line item added */ 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. Returns the `UUID` of the newly added line item, or an empty string if the user dismissed an oversell guard modal. Throws an error if POS fails to add the line item due to validation or system errors. + * * @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 - * @returns {string} the uuid of the line item added + * @returns {string} the UUID of the line item added, or the empty string if the user dismissed an oversell guard modal + * @throws {Error} if POS fails to add the line item */ 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`. 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 with enhanced validation and conflict resolution. + * * @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 with improved error handling for non-existent keys. + * * @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`. Properties are merged with existing line item properties for metadata storage and tracking with enhanced validation. + * * @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 */ @@ -106,20 +139,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` and their respective properties for efficient bulk operations with enhanced validation and error reporting. + * * @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 with improved error handling. + * * @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`. Specify the discount type (`'Percentage'` or `'FixedAmount'`), title, and amount value with improved discount allocation tracking. + * * @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 @@ -132,19 +171,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 with enhanced validation and allocation tracking. + * * @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 with enhanced staff validation and tracking. + * * @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 with improved validation and error handling. + * * @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. */ @@ -153,23 +198,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 with enhanced address validation and formatting. + * * @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 with improved error handling for invalid address `IDs`. + * * @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 with enhanced validation. + * * @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/render/api/connectivity-api/connectivity-api.ts b/packages/ui-extensions/src/surfaces/point-of-sale/render/api/connectivity-api/connectivity-api.ts index af3329a9c5..0d4a078118 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/render/api/connectivity-api/connectivity-api.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/render/api/connectivity-api/connectivity-api.ts @@ -2,23 +2,25 @@ 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 is connected or disconnected from the Internet. + */ export interface ConnectivityState { /** - * Whether the device is connected to the internet + * Whether the device is connected to the Internet. Returns either `Connected` or `Disconnected` to indicate the current Internet connectivity status. Use for implementing connectivity-aware functionality, displaying connectivity indicators, or controlling network-dependent features. */ 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 connectivity-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/render/api/customer-api/customer-api.ts b/packages/ui-extensions/src/surfaces/point-of-sale/render/api/customer-api/customer-api.ts index cf7f811aa9..36b23b094c 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/render/api/customer-api/customer-api.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/render/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 `shopify.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/render/api/device-api/device-api.ts b/packages/ui-extensions/src/surfaces/point-of-sale/render/api/device-api/device-api.ts index ce49af2a2a..cca4923b8f 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/render/api/device-api/device-api.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/render/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 `shopify.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/render/api/draft-order-api/draft-order-api.ts b/packages/ui-extensions/src/surfaces/point-of-sale/render/api/draft-order-api/draft-order-api.ts index 83f2d88339..c3f9f73c36 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/render/api/draft-order-api/draft-order-api.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/render/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 `shopify.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/render/api/locale-api/locale-api.ts b/packages/ui-extensions/src/surfaces/point-of-sale/render/api/locale-api/locale-api.ts index ad9916c70d..f8f712d939 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/render/api/locale-api/locale-api.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/render/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/render/api/navigation-api/navigation-api.ts b/packages/ui-extensions/src/surfaces/point-of-sale/render/api/navigation-api/navigation-api.ts index 53b22de5d1..0b449e797e 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/render/api/navigation-api/navigation-api.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/render/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/render/api/order-api/order-api.ts b/packages/ui-extensions/src/surfaces/point-of-sale/render/api/order-api/order-api.ts index 8cbd6af9e5..349f6308f0 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/render/api/order-api/order-api.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/render/api/order-api/order-api.ts @@ -1,26 +1,26 @@ /** - * Interface to access the order + * The `OrderApi` object provides access to order data in order-specific extension contexts. Access this property through `shopify.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 + * The `OrderApi` object provides access to order data. Access this property through `shopify.order` to interact with the current order context. */ 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/render/api/print-api/print-api.ts b/packages/ui-extensions/src/surfaces/point-of-sale/render/api/print-api/print-api.ts index 62f275454e..e411930e0b 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/render/api/print-api/print-api.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/render/api/print-api/print-api.ts @@ -1,29 +1,21 @@ -/** - * Access the print API for printing functionality - */ export interface PrintApiContent { /** - * Trigger a print dialog. + * Triggers a print dialog for the specified document source. The `print()` method accepts either: * - * The src must be either: - * - A relative path that will be appended to your app's [application_url](/docs/apps/build/cli-for-apps/app-configuration#application_url) + * - A relative path that will be appended to your app's [application_url](/docs/apps/build/cli-for-apps/app-configuration) * - A full URL to your app's backend that will be used to return the document to print * - * Supported document types: - * - HTML documents (recommended for best printing experience) - * - Text files - * - Image files (PNG, JPEG, etc.) - * - PDF files (Note: On Android devices, PDFs will be downloaded and must be printed using an external application) - * - * @param src the source URL of the content to print. - * @returns Promise that resolves when content is ready and native print dialog appears. + * Returns a promise that resolves when content is ready and the native print dialog appears. Use for printing custom documents, receipts, labels, or reports. */ print(src: string): Promise; } /** - * Interface for printing + * The `PrintApi` object provides methods for triggering document printing. Access these methods through `api.print` to initiate print operations with various document types. */ export interface PrintApi { + /** + * Provides access to print functionality for triggering the native print dialog with custom documents. + */ print: PrintApiContent; } diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/render/api/product-api/product-api.ts b/packages/ui-extensions/src/surfaces/point-of-sale/render/api/product-api/product-api.ts index 143c1e4f05..6e602ad935 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/render/api/product-api/product-api.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/render/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 `shopify.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/render/api/product-search-api/product-search-api.ts b/packages/ui-extensions/src/surfaces/point-of-sale/render/api/product-search-api/product-search-api.ts index bf9f2660ef..3a91d33824 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/render/api/product-search-api/product-search-api.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/render/api/product-search-api/product-search-api.ts @@ -9,7 +9,7 @@ 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 { /** @@ -23,7 +23,7 @@ export interface PaginationParams { } /** - * 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 { /** @@ -37,47 +37,61 @@ export interface ProductSearchParams extends PaginationParams { } 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 +101,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/render/api/scanner-api/scanner-api.ts b/packages/ui-extensions/src/surfaces/point-of-sale/render/api/scanner-api/scanner-api.ts index c9a55745ba..7aa53e15d0 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/render/api/scanner-api/scanner-api.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/render/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/render/api/session-api/session-api.ts b/packages/ui-extensions/src/surfaces/point-of-sale/render/api/session-api/session-api.ts index e7cd2f06fd..bc4185c573 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/render/api/session-api/session-api.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/render/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 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 `shopify.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). */ export interface SessionApi { session: SessionApiContent; diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/render/api/toast-api/toast-api.ts b/packages/ui-extensions/src/surfaces/point-of-sale/render/api/toast-api/toast-api.ts index 160d8651a8..740a133042 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/render/api/toast-api/toast-api.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/render/api/toast-api/toast-api.ts @@ -1,16 +1,26 @@ +/** + * 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 should remain visible before automatically dismissing. If not specified, the toast will use the default system duration. Use shorter durations for simple confirmations and longer durations for important messages that users need time to read. + */ 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 `shopify.toast` to show user feedback and status updates. + */ export interface ToastApi { toast: ToastApiContent; } diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/render/components/Badge/Badge.ts b/packages/ui-extensions/src/surfaces/point-of-sale/render/components/Badge/Badge.ts index c71912c0d3..8aa828ba98 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/render/components/Badge/Badge.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/render/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/render/components/Banner/Banner.ts b/packages/ui-extensions/src/surfaces/point-of-sale/render/components/Banner/Banner.ts index cea3ad5824..15fc72d444 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/render/components/Banner/Banner.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/render/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/render/components/Button/Button.ts b/packages/ui-extensions/src/surfaces/point-of-sale/render/components/Button/Button.ts index a675efe5e0..063f7b27b2 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/render/components/Button/Button.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/render/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/render/components/CameraScanner/CameraScanner.ts b/packages/ui-extensions/src/surfaces/point-of-sale/render/components/CameraScanner/CameraScanner.ts index 3a3d649595..3257ac8c37 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/render/components/CameraScanner/CameraScanner.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/render/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/render/components/DatePicker/DatePicker.ts b/packages/ui-extensions/src/surfaces/point-of-sale/render/components/DatePicker/DatePicker.ts index 92c75094a7..dfce63f0c8 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/render/components/DatePicker/DatePicker.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/render/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/render/components/Dialog/Dialog.ts b/packages/ui-extensions/src/surfaces/point-of-sale/render/components/Dialog/Dialog.ts index d7de98d31f..645bce5318 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/render/components/Dialog/Dialog.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/render/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/render/components/FormattedTextField/FormattedTextField.ts b/packages/ui-extensions/src/surfaces/point-of-sale/render/components/FormattedTextField/FormattedTextField.ts index b35420925e..bc645d8bdf 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/render/components/FormattedTextField/FormattedTextField.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/render/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/render/components/Icon/Icon.ts b/packages/ui-extensions/src/surfaces/point-of-sale/render/components/Icon/Icon.ts index 52ba0bf5ba..6acf51525f 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/render/components/Icon/Icon.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/render/components/Icon/Icon.ts @@ -1,100 +1,286 @@ import {createRemoteComponent} from '@remote-ui/core'; +/** + * @deprecated Use `IconName` instead. These deprecated icon names will be removed in 2025-10. + */ +export type DeprecatedIconName = + | 'add-customer' /** Add customer symbol. Use for creating new customer accounts. Removed in version 2025-10. Use `'customer-outlined'` instead. */ + | 'analytics' /** Analytics symbol. Use for data analysis and reports. Removed in version 2025-10. Use `'analytics'` from `IconName` instead. */ + | 'apps' /** Applications symbol. Use for app launchers. Removed in version 2025-10. Use `'apps'` from `IconName` instead. */ + | 'arrow' /** A generic arrow symbol. Removed in version 2025-10. Use specific directional arrows instead (`'arrow-up'`, `'arrow-down'`, `'arrow-left'`, `'arrow-right'`). */ + | 'arrow-left' /** Left arrow symbol. Removed in version 2025-10. Use `'arrow-left'` from `IconName` instead. */ + | 'backspace' /** A backspace symbol. Removed in version 2025-10. Use `'backspace'` from `IconName` instead. */ + | 'card-reader' /** Card reader device symbol. Removed in version 2025-10. Use `'card-reader'` from `IconName` instead. */ + | 'call' /** A phone call symbol. Removed in version 2025-10. Use `'call'` from `IconName` instead. */ + | 'cancel' /** A cancel symbol. Removed in version 2025-10. Use `'cancel'` from `IconName` instead. */ + | 'not-stocked' /** Not stocked symbol. Removed in version 2025-10. Use `'not-stocked'` from `IconName` instead. */ + | 'cash' /** A cash symbol. Removed in version 2025-10. Use `'cash'` from `IconName` instead. */ + | 'checkmark' /** A checkmark symbol. Removed in version 2025-10. Use `'checkmark'` from `IconName` instead. */ + | 'caret-down' /** Small downward caret. Removed in version 2025-10. Use `'caret-down'` from `IconName` instead. */ + | 'checkmark-active' /** Active checkmark symbol. Removed in version 2025-10. Use `'checkmark-active'` from `IconName` instead. */ + | 'checkmark-inactive' /** Inactive checkmark symbol. Removed in version 2025-10. Use `'checkmark-inactive'` from `IconName` instead. */ + | 'chevron-up' /** Upward chevron. Removed in version 2025-10. Use `'chevron-up'` from `IconName` instead. */ + | 'chevron-right' /** Rightward chevron. Removed in version 2025-10. Use `'chevron-right'` from `IconName` instead. */ + | 'chevron-down' /** Downward chevron. Removed in version 2025-10. Use `'chevron-down'` from `IconName` instead. */ + | 'circle-alert' /** Alert symbol in circle. Removed in version 2025-10. Use `'circle-alert'` from `IconName` instead. */ + | 'circle-cancel' /** Cancel symbol in circle. Removed in version 2025-10. Use `'circle-cancel'` from `IconName` instead. */ + | 'circle-checkmark' /** Checkmark in circle. Removed in version 2025-10. Use `'circle-checkmark'` from `IconName` instead. */ + | 'circle-disconnected' /** Disconnected circle symbol. Removed in version 2025-10. Use `'circle-disconnected'` from `IconName` instead. */ + | 'circle-info' /** Information symbol in circle. Removed in version 2025-10. Use `'circle-info'` from `IconName` instead. */ + | 'circle-outline' /** Simple circle outline. Removed in version 2025-10. Use `'circle-outline'` from `IconName` instead. */ + | 'clock' /** Clock or time symbol. Removed in version 2025-10. Use `'clock'` from `IconName` instead. */ + | 'collections' /** Product collections symbol. Removed in version 2025-10. Use `'collection'` from `IconName` instead. */ + | 'copy' /** Copy or duplicate symbol. Removed in version 2025-10. Use `'copy'` from `IconName` instead. */ + | 'credit-card' /** Credit card symbol. Removed in version 2025-10. Use `'credit-card'` from `IconName` instead. */ + | 'custom-payment' /** Custom payment method symbol. Removed in version 2025-10. Use `'custom-payment'` from `IconName` instead. */ + | 'custom-sale' /** Custom sale symbol. Removed in version 2025-10. Use `'custom-sale'` from `IconName` instead. */ + | 'discount' /** Discount or sale symbol. Removed in version 2025-10. Use `'discount'` from `IconName` instead. */ + | 'external-link' /** External link symbol. Removed in version 2025-10. Use `'external-link'` from `IconName` instead. */ + | 'flag' /** Flag or marker symbol. Removed in version 2025-10. Use `'flag'` from `IconName` instead. */ + | 'flip-camera' /** Camera rotation or flip symbol. Removed in version 2025-10. Use `'flip-camera'` from `IconName` instead. */ + | 'gallery-view' /** Gallery view symbol. Removed in version 2025-10. Use `'gallery-view'` from `IconName` instead. */ + | 'gift-card' /** Gift card symbol. Removed in version 2025-10. Use `'gift-card'` from `IconName` instead. */ + | 'help' /** Help symbol. Removed in version 2025-10. Use `'help'` from `IconName` instead. */ + | 'hide-keyboard' /** Hide keyboard symbol. Removed in version 2025-10. Use `'hide-keyboard'` from `IconName` instead. */ + | 'home' /** Home symbol. Removed in version 2025-10. Use `'home-filled'` or `'home-outlined'` from `IconName` instead. */ + | 'horizontal-dots' /** Horizontal dots or more options symbol. Removed in version 2025-10. Use `'horizontal-dots'` from `IconName` instead. */ + | 'keypad' /** Numeric keypad symbol. Removed in version 2025-10. Use `'keypad'` from `IconName` instead. */ + | 'lightning' /** Lightning bolt symbol. Removed in version 2025-10. Use `'lightning'` from `IconName` instead. */ + | 'link' /** Link or chain symbol. Removed in version 2025-10. Use `'link'` from `IconName` instead. */ + | 'list' /** List symbol. Removed in version 2025-10. Use `'list'` from `IconName` instead. */ + | 'list-view' /** List view layout symbol. Removed in version 2025-10. Use `'list-view'` from `IconName` instead. */ + | 'lock' /** Lock or security symbol. Removed in version 2025-10. Use `'lock'` from `IconName` instead. */ + | 'mail' /** Email or message symbol. Removed in version 2025-10. Use `'mail'` from `IconName` instead. */ + | 'available-at-other-locations' /** Available at other locations symbol. Removed in version 2025-10. Use appropriate `IconName` alternative. */ + | 'menu' /** Menu symbol. Removed in version 2025-10. Use `'horizontal-dots'` or other `IconName` alternative. */ + | 'minus' /** Minus or subtract symbol. Removed in version 2025-10. Use `'minus'` from `IconName` instead. */ + | 'mobile' /** Mobile phone symbol. Removed in version 2025-10. Use `'mobile'` from `IconName` instead. */ + | 'note-report' /** Note or report symbol. Removed in version 2025-10. Use `'note-report'` from `IconName` instead. */ + | 'drawer' /** Cash drawer symbol. Removed in version 2025-10. Use `'drawer'` from `IconName` instead. */ + | 'orders' /** Orders symbol. Removed in version 2025-10. Use `'orders-filled'` or `'orders-outlined'` from `IconName` instead. */ + | 'shopify-payments' /** Shopify payments symbol. Removed in version 2025-10. Use `'shopify-payments'` from `IconName` instead. */ + | 'play-button' /** Play button symbol. Removed in version 2025-10. Use `'play-button'` from `IconName` instead. */ + | 'plus' /** Plus or add symbol. Removed in version 2025-10. Use `'plus'` from `IconName` instead. */ + | 'products' /** Products symbol. Removed in version 2025-10. Use `'products-filled'` or `'products-outlined'` from `IconName` instead. */ + | 'radio-active' /** Active radio button symbol. Removed in version 2025-10. Use `'radio-active'` from `IconName` instead. */ + | 'radio-inactive' /** Inactive radio button symbol. Removed in version 2025-10. Use `'radio-inactive'` from `IconName` instead. */ + | 'rearrange' /** Rearrange or reorder symbol. Removed in version 2025-10. Use `'rearrange'` from `IconName` instead. */ + | 'receipt' /** Receipt symbol. Removed in version 2025-10. Use `'receipt'` from `IconName` instead. */ + | 'refresh' /** Refresh or reload symbol. Removed in version 2025-10. Use `'refresh'` from `IconName` instead. */ + | 'register' /** Cash register symbol. Removed in version 2025-10. Use `'register'` from `IconName` instead. */ + | 'retrieve-cart' /** Retrieve cart symbol. Removed in version 2025-10. Use `'retrieve-cart'` from `IconName` instead. */ + | 'image-placeholder' /** Image placeholder symbol. Removed in version 2025-10. Use `'image'` from `IconName` instead. */ + | 'save-cart' /** Save cart symbol. Removed in version 2025-10. Use `'save-cart'` from `IconName` instead. */ + | 'scan-barcode' /** Barcode scanning symbol. Removed in version 2025-10. Use `'scan-barcode'` from `IconName` instead. */ + | 'search' /** Search or magnifying glass symbol. Removed in version 2025-10. Use `'search'` from `IconName` instead. */ + | 'send' /** Send or submit symbol. Removed in version 2025-10. Use `'send'` from `IconName` instead. */ + | 'settings' /** Settings or gear symbol. Removed in version 2025-10. Use `'settings'` from `IconName` instead. */ + | 'shipment' /** Shipment symbol. Removed in version 2025-10. Use `'fulfillment-shipment'` from `IconName` instead. */ + | 'split-payment' /** Split payment symbol. Removed in version 2025-10. Use `'split-payment'` from `IconName` instead. */ + | 'sort' /** Sort or arrange symbol. Removed in version 2025-10. Use `'sort'` from `IconName` instead. */ + | 'staff' /** Staff or employee symbol. Removed in version 2025-10. Use `'staff'` from `IconName` instead. */ + | 'star' /** Star symbol. Removed in version 2025-10. Use `'star'` from `IconName` instead. */ + | 'unordered-list' /** Unordered list symbol. Removed in version 2025-10. Use `'unordered-list'` from `IconName` instead. */ + | 'connectivity-warning' /** Connectivity warning symbol. Removed in version 2025-10. Use `'connectivity-issue'` from `IconName` instead. */ + | 'internet' /** Internet connectivity symbol. Removed in version 2025-10. Use `'connectivity'` or `'no-internet'` from `IconName` instead. */ + | 'delivery' /** Delivery symbol. Removed in version 2025-10. Use `'fulfillment-delivery'` from `IconName` instead. */ + | 'shop-pay' /** Shop Pay symbol. Removed in version 2025-10. Use `'shop-pay'` from `IconName` instead. */; + +/** + * @deprecated Use `IconSize` instead. These deprecated icon sizes will be removed in 2025-10. + */ +export type DeprecatedIconSize = + | 'minor' /** A minor size for small elements. Removed in version 2025-10. Use `'s'` or `'m'` size instead. */ + | 'major' /** A major size for prominent elements. Removed in version 2025-10. Use `'l'` or `'xl'` size instead. */ + | 'spot' /** A spot size for specific use cases. Removed in version 2025-10. Use `'m'` or `'l'` size instead. */ + | 'caption' /** A caption size for small text accompaniment. Removed in version 2025-10. Use `'s'` size instead. */ + | 'badge' /** A badge size for small indicators. Removed in version 2025-10. Use `'s'` size instead. */; + export type IconName = - | 'add-customer' - | 'analytics' - | 'apps' - | 'arrow' - | 'arrow-left' - | 'backspace' - | 'card-reader' - | 'call' - | 'cancel' - | 'not-stocked' - | 'cash' - | 'checkmark' - | 'caret-down' - | 'checkmark-active' - | 'checkmark-inactive' - | 'chevron-up' - | 'chevron-right' - | 'chevron-down' - | 'circle-alert' - | 'circle-cancel' - | 'circle-checkmark' - | 'circle-disconnected' - | 'circle-info' - | 'circle-outline' - | 'clock' - | 'collections' - | 'copy' - | 'credit-card' - | 'custom-payment' - | 'custom-sale' - | 'discount' - | 'external-link' - | 'flag' - | 'flip-camera' - | 'gallery-view' - | 'gift-card' - | 'help' - | 'hide-keyboard' - | 'home' - | 'horizontal-dots' - | 'keypad' - | 'lightning' - | 'link' - | 'list' - | 'list-view' - | 'lock' - | 'mail' - | 'available-at-other-locations' - | 'menu' - | 'minus' - | 'mobile' - | 'note-report' - | 'drawer' - | 'orders' - | 'shopify-payments' - | 'play-button' - | 'plus' - | 'products' - | 'radio-active' - | 'radio-inactive' - | 'rearrange' - | 'receipt' - | 'refresh' - | 'register' - | 'retrieve-cart' - | 'image-placeholder' - | 'save-cart' - | 'scan-barcode' - | 'search' - | 'send' - | 'settings' - | 'shipment' - | 'split-payment' - | 'sort' - | 'staff' - | 'star' - | 'unordered-list' - | 'connectivity-warning' - | 'internet' - | 'delivery' - | 'shop-pay'; + | 'add-customer' /** Add customer symbol. Use for creating new customer accounts. Removed in version 2025-10. Use `IconName` equivalent instead. */ + | 'activity' /** An activity or action indicator. Use for activity feeds, action logs, or recent activity displays. */ + | 'analytics' /** Analytics symbol. Use for data analysis and reports. Removed in version 2025-10. Use `IconName` equivalent instead. */ + | 'apps' /** Applications symbol. Use for app launchers. Removed in version 2025-10. Use `IconName` equivalent instead. */ + | 'arrow-down' /** A downward pointing arrow. Use for dropdown menus, collapsing content, downloading actions, or indicating downward movement. */ + | 'arrow-left' /** A left arrow symbol. Removed in version 2025-10. Use `IconName` equivalent instead. */ + | 'arrow-right' /** A rightward pointing arrow. Use for forward navigation, next actions, or indicating rightward movement and progression. */ + | 'arrow-up' /** An upward pointing arrow. Use for expanding content, uploading actions, or indicating upward movement and elevation. */ + | 'backspace' /** A backspace symbol. Removed in version 2025-10. Use `IconName` equivalent instead. */ + | 'call' /** A phone call symbol. Removed in version 2025-10. Use `IconName` equivalent instead. */ + | 'cancel-fulfillment' /** A cancel fulfillment symbol. Use for stopping order fulfillment, canceling shipments, or fulfillment management. */ + | 'cancel' /** A cancel symbol. Removed in version 2025-10. Use `IconName` equivalent instead. */ + | 'card-reader' /** A card reader symbol. Removed in version 2025-10. Use `IconName` equivalent instead. */ + | 'caret-down' /** A small downward caret. Use for dropdown indicators, collapsible sections, or subtle directional cues. */ + | 'caret-up' /** A small upward caret. Use for expandable sections, sort indicators, or subtle upward directional cues. */ + | 'cart-filled' /** A filled shopping cart. Use to indicate items in cart, active shopping session, or cart with contents. */ + | 'cart-outlined' /** A shopping cart outline. Use for shopping functionality, adding items to cart, or e-commerce actions. */ + | 'cash' /** A cash symbol. Removed in version 2025-10. Use `IconName` equivalent instead. */ + | 'checklist' /** A checklist symbol. Use for tasks, order fulfillment, inventory checks, or process completion. */ + | 'checkmark' /** A checkmark symbol. Removed in version 2025-10. Use `IconName` equivalent instead. */ + | 'checkmark-active' /** Active checkmark symbol. Use for selected items, active confirmations, or enabled states. */ + | 'checkmark-inactive' /** An inactive checkmark symbol. Use for unselected items, disabled confirmations, or inactive states. */ + | 'chevron-down' /** A downward chevron. Use for dropdown menus, expandable content, or indicating downward navigation. */ + | 'chevron-left' /** A leftward chevron. Use for back navigation, previous items, or leftward movement in carousels and lists. */ + | 'chevron-right' /** A rightward chevron. Use for forward navigation, next items, or rightward movement and progression. */ + | 'chevron-up' /** An upward chevron. Use for collapsible content, scroll to top, or indicating upward navigation. */ + | 'circle-alert' /** Alert symbol in circle. Use for system alerts, validation errors, or important notifications that require attention. */ + | 'circle-cancel' /** A cancel symbol in circle. Use for cancellation actions, error states, or removing items with emphasis. */ + | 'circle-checkmark' /** A checkmark in circle. Use for completed tasks, successful operations, or positive confirmation states. */ + | 'circle-disconnected' /** A disconnected circle symbol. Use for offline states, connection issues, or unavailable services. */ + | 'circle-info' /** An information symbol in circle. Use for help content, additional details, or informational messages. */ + | 'circle-outline' /** A simple circle outline. Use for radio buttons, status indicators, or basic geometric markers. */ + | 'clock' /** A clock or time symbol. Use for scheduling, time tracking, business hours, or temporal information. */ + | 'collection' /** A product collection or group symbol. Use for product categories, grouped items, or collection management. */ + | 'connectivity' /** A connectivity indicator. Use for network status, connection quality, or connectivity features. */ + | 'connectivity-issue' /** A connectivity problem indicator. Use for network issues, connection warnings, or connectivity troubleshooting. */ + | 'connectivity-critical-issue' /** A critical connectivity problem. Use for severe network failures, critical connection errors, or urgent connectivity issues. */ + | 'copy' /** A copy or duplicate symbol. Use for copying items, duplicating records, or replication actions. */ + | 'credit-card' /** A credit card symbol. Use for payment methods, card transactions, or financial operations. */ + | 'custom-payment' /** A custom payment method symbol. Use for alternative payment options, custom payment processing, or specialized payment types. */ + | 'custom-sale' /** A custom sale symbol. Use for special sales, custom pricing, or non-standard sale transactions. */ + | 'customer-filled' /** A filled customer symbol. Use for active customers, selected customer profiles, or customer highlights. */ + | 'customer-outlined' /** A customer outline symbol. Use for customer accounts, customer profiles, or customer-related features. */ + | 'delete' /** A delete or trash symbol. Use for removing items, deleting records, or destructive actions. */ + | 'desktop' /** A desktop computer symbol. Use for device types, platform indicators, or desktop-specific features. */ + | 'discount' /** A discount or sale symbol. Use for promotions, price reductions, or special offers. */ + | 'discount-automatic' /** Automatic discount symbol. Use for system-applied discounts, automatic promotions, or rule-based reductions. */ + | 'discount-code' /** A discount code symbol. Use for coupon codes, promotional codes, or manual discount entry. */ + | 'discount-custom' /** A custom discount symbol. Use for manual discounts, custom pricing adjustments, or personalized promotions. */ + | 'discount-remove' /** A remove discount symbol. Use for removing applied discounts, canceling promotions, or undoing price reductions. */ + | 'dockside' /** A dockside or shipping dock symbol. Use for shipping operations, dock management, or logistics features. */ + | 'draft-orders' /** A draft orders symbol. Use for incomplete orders, order drafts, or pending order creation. */ + | 'drawer' /** A cash drawer symbol. Use for cash register operations, drawer opening, or cash management. */ + | 'exchange' /** An exchange or swap symbol. Use for product exchanges, return processing, or item swapping. */ + | 'external-link' /** An external link symbol. Use for links that open in new windows, external resources, or outside navigation. */ + | 'fees' /** A fees symbol. Use for transaction fees, additional charges, or fee management. */ + | 'flag' /** A flag or marker symbol. Use for flagging items, marking important content, or status indicators. */ + | 'flip-camera' /** A camera rotation or flip symbol. Use for switching camera views, rotating images, or camera-related controls. */ + | 'fulfillment-delivery' /** A delivery fulfillment symbol. Use for delivery options, shipping fulfillment, or delivery tracking. */ + | 'fulfillment-shipment' /** A shipment fulfillment symbol. Use for shipping operations, package fulfillment, or shipment tracking. */ + | 'gallery-view' /** A gallery view symbol. Use for image galleries, grid layouts, or visual content displays. */ + | 'gift-card' /** A gift card symbol. Use for gift card sales, redemption, or gift card management features. */ + | 'help' /** A help symbol. Use for help features, support, or informational assistance. */ + | 'hide' /** A hide or visibility off symbol. Use for hiding content, privacy controls, or visibility toggles. */ + | 'hide-keyboard' /** A hide keyboard symbol. Use for dismissing on-screen keyboards or input controls. */ + | 'home-filled' /** A filled home symbol. Use for active home state, main navigation, or primary dashboard indicator. */ + | 'home-outlined' /** A home outline symbol. Use for home navigation, main dashboard, or returning to start screen. */ + | 'horizontal-dots' /** A horizontal dots or more options symbol. Use for additional actions, overflow menus, or more options. */ + | 'image' /** A single image symbol. Use for image upload, photo features, or visual content indicators. */ + | 'images' /** A multiple images symbol. Use for image galleries, bulk photo operations, or media collections. */ + | 'inventory-adjustments' /** An inventory adjustments symbol. Use for stock adjustments, inventory corrections, or quantity modifications. */ + | 'inventory-counts' /** An inventory counts symbol. Use for stock counting, inventory audits, or quantity verification. */ + | 'inventory-po' /** A purchase order inventory symbol. Use for purchase orders, inventory procurement, or stock ordering. */ + | 'inventory-transfer' /** An inventory transfer symbol. Use for moving stock between locations, transfers, or redistribution. */ + | 'keypad' /** A numeric keypad symbol. Use for number entry, PIN input, or calculator functions. */ + | 'learn' /** A learning or education symbol. Use for training, tutorials, or educational features. */ + | 'lightning' /** A lightning bolt symbol. Use for power, energy, fast actions, or high-priority features. */ + | 'link' /** A link or chain symbol. Use for hyperlinks, connections, or linking functionality. */ + | 'list' /** A list symbol. Use for list views, itemized content, or list formatting. */ + | 'list-view' /** A list view layout symbol. Use for switching to list layout, organizing content, or list-based displays. */ + | 'location' /** A location or map pin symbol. Use for store locations, addresses, or geographic features. */ + | 'lock' /** A lock or security symbol. Use for secure features, locked content, or security settings. */ + | 'low-battery' /** A low battery indicator. Use for device status, power warnings, or battery-related notifications. */ + | 'mail' /** An email or message symbol. Use for email functionality, messaging, or communication features. */ + | 'maximize' /** A maximize or expand symbol. Use for fullscreen mode, expanding windows, or enlarging content. */ + | 'minimize' /** A minimize or collapse symbol. Use for reducing windows, collapsing content, or minimizing interfaces. */ + | 'minus' /** A minus or subtract symbol. Use for decreasing quantities, removing items, or subtraction operations. */ + | 'mobile' /** A mobile phone symbol. Use for mobile features, device types, or mobile-specific functionality. */ + | 'more-filled' /** A filled more options symbol. Use for active additional actions, prominent overflow menus, or emphasized options. */ + | 'more-outlined' /** An outlined more options symbol. Use for additional actions, overflow menus, or more options. */ + | 'no-internet' /** A no internet connection symbol. Use for offline states, connection failures, or network unavailability. */ + | 'note-report' /** A note or report symbol. Use for notes, documentation, reports, or text content features. */ + | 'not-stocked' /** A not stocked symbol. Removed in version 2025-10. Use `IconName` equivalent instead. */ + | 'orders-filled' /** A filled orders symbol. Use for completed orders, active order states, or order fulfillment. */ + | 'orders-outlined' /** An orders outline symbol. Use for order management, order history, or order-related functions. */ + | 'pencil' /** A pencil or edit symbol. Use for editing content, modifying records, or entering edit mode. */ + | 'play-button' /** A play button symbol. Use for starting processes, playing media, or initiating actions. */ + | 'plus' /** A plus or add symbol. Use for adding items, creating new content, or addition operations. */ + | 'point-of-sale' /** A point of sale system symbol. Use for POS features, retail operations, or sales terminals. */ + | 'print' /** A print symbol. Use for printing receipts, documents, or print-related functionality. */ + | 'pro' /** A pro or premium symbol. Use for professional features, premium content, or advanced functionality. */ + | 'products-filled' /** A filled products symbol. Use for active products, selected items, or product highlights. */ + | 'products-outlined' /** A products outline symbol. Use for product management, catalog features, or product-related functions. */ + | 'radio-active' /** Active radio button symbol. Use for selected radio options, active choices, or enabled selections. */ + | 'radio-inactive' /** An inactive radio button symbol. Use for unselected radio options, inactive choices, or disabled selections. */ + | 'reassign-fulfillment' /** A reassign fulfillment symbol. Use for changing fulfillment locations, reassigning orders, or fulfillment redirection. */ + | 'rearrange' /** A rearrange or reorder symbol. Use for reordering lists, organizing content, or arrangement controls. */ + | 'receipt' /** A receipt symbol. Use for transaction receipts, purchase confirmations, or receipt management. */ + | 'refresh' /** A refresh or reload symbol. Use for updating content, refreshing data, or reload operations. */ + | 'register' /** A cash register symbol. Use for register operations, cash handling, or traditional POS functions. */ + | 'return' /** A return symbol. Use for product returns, refund processing, or return management. */ + | 'retrieve-cart' /** A retrieve cart symbol. Use for recovering saved carts, loading previous carts, or cart restoration. */ + | 'save-cart' /** A save cart symbol. Use for saving current cart, cart preservation, or cart storage. */ + | 'scan-barcode' /** A barcode scanning symbol. Use for product scanning, inventory management, or barcode-related functionality. */ + | 'scan-qr-code' /** A QR code scanning symbol. Use for QR code features, digital scanning, or code-based interactions. */ + | 'search' /** A search or magnifying glass symbol. Use for search functionality, finding content, or lookup features. */ + | 'send' /** A send or submit symbol. Use for sending messages, submitting forms, or transmission actions. */ + | 'send-cart' /** A send cart symbol. Use for sharing cart contents, sending cart to another device, or cart transfer actions. */ + | 'settings' /** A settings or gear symbol. Use for configuration, preferences, or system settings. */ + | 'shop-app' /** A shop app symbol. Use for shopping app features, mobile commerce, or app-specific functionality. */ + | 'shop-pay' /** A shop pay symbol. Use for Shop Pay payment method, express checkout, or Shopify payment features. */ + | 'shopify-payments' /** A shopify payments symbol. Use for Shopify payment processing, payment gateway features, or payment management. */ + | 'sort' /** A sort or arrange symbol. Use for sorting lists, organizing content, or arrangement controls. */ + | 'split-payment' /** A split payment symbol. Use for divided payments, partial payments, or payment splitting features. */ + | 'staff' /** A staff or employee symbol. Use for staff management, employee features, or personnel-related functions. */ + | 'star' /** A star symbol. Use for ratings, favorites, or highlighting important content. */ + | 'store' /** A store or shop symbol. Use for store information, retail locations, or shop-related features. */ + | 'tablet-l' /** A large tablet device symbol. Use for large tablet features, device types, or tablet-specific functionality. */ + | 'tablet-s' /** A small tablet device symbol. Use for small tablet features, compact devices, or mini tablet functionality. */ + | 'tap-to-pay' /** A tap to pay symbol. Use for contactless payments, NFC transactions, or tap payment features. */ + | 'unlock' /** An unlock symbol. Use for unlocking features, accessing content, or security controls. */ + | 'unordered-list' /** An unordered list symbol. Use for bulleted lists, itemized content, or list formatting. */ + | 'variant' /** A product variant symbol. Use for product variations, different options, or variant management. */ + | 'view' /** A view or eye symbol. Use for viewing content, visibility controls, or display options. */ + | 'void-shipping-label' /** A void shipping label symbol. Use for canceling shipping labels, voiding shipments, or shipping corrections. */; + +export type IconSize = + | 's' /** A small icon size. Use for compact spaces, inline text accompaniment, or when minimal visual weight is needed. */ + | 'm' /** A medium icon size. Use for secondary navigation, list items, or compact interface elements. */ + | 'l' /** A large icon size (default). Provides optimal visibility and balance for most interface elements, primary actions, and standard components. */ + | 'xl' /** An extra large icon size. Use for prominent actions, headers, or when icons need maximum visibility and impact. */; -export type IconSize = 'minor' | 'major' | 'spot' | 'caption' | 'badge'; +export type IconTone = + | 'icon-primary' /** Primary icon color. Use for main content and standard icon displays with default contrast. */ + | 'icon-inverse' /** Inverse icon color. Use for icons on dark backgrounds or to create contrast in inverse color schemes. */ + | 'icon-subdued' /** Subdued icon color. Use for secondary icons, less prominent content, or when reduced visual emphasis is needed. */ + | 'icon-disabled' /** Disabled icon color. Use for inactive or unavailable icons that users cannot interact with. */ + | 'icon-warning' /** Warning icon color. Use for caution states, important notices, or situations requiring attention. */ + | 'icon-critical' /** Critical icon color. Use for errors, urgent issues, or destructive actions requiring immediate attention. */ + | 'icon-success' /** Success icon color. Use for positive outcomes, confirmations, or completed actions. */ + | 'icon-interactive' /** Interactive icon color. Use for clickable icons, links, or interactive elements to indicate interactivity. */ + | 'icon-highlight' /** Highlight icon color. Use for emphasized content, featured items, or icons requiring special attention. */ + | 'icon-shoppay' /** Shop Pay brand color. Use specifically for Shop Pay related features and branding. */ + | 'icon-static-light' /** Static light icon color. Use for icons on light backgrounds with fixed, non-adaptive coloring. */ + | 'icon-static-dark' /** Static dark icon color. Use for icons on dark backgrounds with fixed, non-adaptive coloring. */ + | 'icon-inactive' /** Inactive icon color. Use for temporarily disabled or inactive interface elements. */ + | 'icon-badge-neutral' /** Neutral badge icon color. Use for general badge icons without specific semantic meaning. */ + | 'icon-search' /** Search icon color. Use specifically for search-related icons and search interface elements. */ + | 'icon-tile-default' /** Default tile icon color. Use for standard tile icons in grid or tile-based layouts. */ + | 'icon-tile-stack' /** Stack tile icon color. Use for grouped or stacked tile icons in organizational views. */ + | 'icon-tile-disabled' /** Disabled tile icon color. Use for inactive or unavailable tile icons in grid layouts. */ + | 'icon-tile-pink' /** Pink tile icon color. Use for color-coded pink category tiles or themed content. */ + | 'icon-tile-purple' /** Purple tile icon color. Use for color-coded purple category tiles or themed content. */ + | 'icon-tile-orange' /** Orange tile icon color. Use for color-coded orange category tiles or themed content. */ + | 'icon-subnavigation-inactive' /** Inactive sub-navigation icon color. Use for unselected items in secondary navigation menus. */ + | 'icon-primary-pressed' /** Pressed primary icon color. Use for the pressed state of primary interactive icons. */; 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 | DeprecatedIconName; + /** + * The size of the icon. Use `'s'` for small icons, `'m'` for medium, `'l'` for large (default), or `'xl'` for extra large. + * + * @defaultValue 'l' */ - name: IconName; + size?: IconSize | DeprecatedIconSize; /** - * Size of the icon. - * @defaultValue 'major' + * The color of the icon. Use semantic tones like `'icon-critical'` for errors, `'icon-warning'` for cautions, `'icon-success'` for confirmations, or contextual tones like `'icon-subdued'` for secondary elements and `'icon-interactive'` for clickable elements. + * + * @defaultValue 'icon-primary' */ - size?: IconSize; + tone?: IconTone; } export const Icon = createRemoteComponent<'Icon', IconProps>('Icon'); diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/render/components/Image/Image.ts b/packages/ui-extensions/src/surfaces/point-of-sale/render/components/Image/Image.ts index 76e571f1e9..6f5f867f0f 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/render/components/Image/Image.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/render/components/Image/Image.ts @@ -1,11 +1,20 @@ import {createRemoteComponent} from '@remote-ui/core'; -export type ImageSize = 's' | 'm' | 'l' | 'xl'; +export type ImageSize = + | 's' /** A small image size. Use for thumbnails, compact layouts, or when minimal space is available for image display. */ + | 'm' /** A medium image size. Use for secondary content, list items, or compact interface elements where space is moderately constrained. */ + | 'l' /** A large image size (default). Provides optimal visibility and balance for most interface elements, product displays, and standard image content. */ + | 'xl' /** An extra large image size. Use for hero images, featured content, or when maximum visual impact and detail visibility are needed. */; /** - * FillResizeMode will apply formatting to the image to fill the container. + * Defines how images are resized and positioned within their containers. Controls image scaling, cropping, and aspect ratio handling. * - * https://reactnative.dev/docs/image#resizemode + * Available resize modes: + * - `center`: Centers the image within its container without scaling. The image maintains its original size and is positioned in the center, potentially leaving empty space or being cropped if the container is smaller. + * - `contain`: Scales the image to fit entirely within the container while maintaining aspect ratio. The entire image will be visible, but there may be empty space if the aspect ratios don't match. + * - `cover`: Scales the image to fill the entire container while maintaining aspect ratio. Parts of the image may be cropped if the aspect ratios don't match, but the container will be completely filled. + * - `repeat`: Repeats the image to fill the container. The image maintains its original size and is tiled both horizontally and vertically to cover the entire container area. + * - `stretch`: Stretches the image to fill the container completely, potentially distorting the aspect ratio. The image will fill the entire container but may appear stretched or compressed. */ export type FillResizeMode = | 'cover' @@ -16,12 +25,12 @@ export type FillResizeMode = export interface ImageProps { /** - * The source of the image to be displayed. + * The source of the image to be displayed. Provide a valid URL to a remote image or a local file resource. When no `src` is provided or the image is loading, a placeholder will be rendered. */ src?: string; /** - * The size or fill size of the image. + * The size or fill behavior of the image. Use `ImageSize` values (`'s'`, `'m'`, `'l'`, `'xl'`) for fixed dimensions, or `FillResizeMode` values (`'cover'`, `'contain'`, `'stretch'`, `'repeat'`, `'center'`) to control how the image fills its container. * * @default 'l' */ diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/render/components/List/List.ts b/packages/ui-extensions/src/surfaces/point-of-sale/render/components/List/List.ts index 21493f0396..805ce3a7c3 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/render/components/List/List.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/render/components/List/List.ts @@ -4,117 +4,131 @@ 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?]; /** - * 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/render/components/Navigator/Navigator.ts b/packages/ui-extensions/src/surfaces/point-of-sale/render/components/Navigator/Navigator.ts index 6433d76768..f3df321b14 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/render/components/Navigator/Navigator.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/render/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/render/components/NumberField/NumberField.ts b/packages/ui-extensions/src/surfaces/point-of-sale/render/components/NumberField/NumberField.ts index 35900c5e65..4582d94f42 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/render/components/NumberField/NumberField.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/render/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/render/components/POSBlock/POSBlock.ts b/packages/ui-extensions/src/surfaces/point-of-sale/render/components/POSBlock/POSBlock.ts index 303edc2ffd..6f8c9b2243 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/render/components/POSBlock/POSBlock.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/render/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/render/components/POSBlock/POSBlockRow.ts b/packages/ui-extensions/src/surfaces/point-of-sale/render/components/POSBlock/POSBlockRow.ts index 645d5d3f96..0e45960296 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/render/components/POSBlock/POSBlockRow.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/render/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/render/components/POSReceiptBlock/POSReceiptBlock.ts b/packages/ui-extensions/src/surfaces/point-of-sale/render/components/POSReceiptBlock/POSReceiptBlock.ts index 9d785b4182..8dba13e3b8 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/render/components/POSReceiptBlock/POSReceiptBlock.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/render/components/POSReceiptBlock/POSReceiptBlock.ts @@ -2,10 +2,6 @@ import {createRemoteComponent} from '@remote-ui/core'; import {QRCode} from '../QRCode/QRCode'; import {Text} from '../Text/Text'; -/** - * Renders a `POSReceiptBlock`. A `POSReceiptBlock` only accepts - * `Text` and `QRCode` as children (more to be added in the future). - */ export interface POSReceiptBlockProps {} export type AllowedChildrenComponents = typeof Text | typeof QRCode; diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/render/components/PinPad/PinPad.ts b/packages/ui-extensions/src/surfaces/point-of-sale/render/components/PinPad/PinPad.ts index b7488f1188..a6f404b06e 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/render/components/PinPad/PinPad.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/render/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/render/components/PrintPreview/PrintPreview.ts b/packages/ui-extensions/src/surfaces/point-of-sale/render/components/PrintPreview/PrintPreview.ts index 3f883bf846..f848ecdbd8 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/render/components/PrintPreview/PrintPreview.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/render/components/PrintPreview/PrintPreview.ts @@ -2,17 +2,7 @@ import {createRemoteComponent} from '@remote-ui/core'; export interface PrintPreviewProps { /** - * The source to print. - * - * The src must be either: - * - A relative path that will be appended to your app's [application_url](/docs/apps/build/cli-for-apps/app-configuration#application_url) - * - A full URL to your app's backend that will be used to return the document - * - * Supported document types: - * - HTML documents (recommended for best printing experience) - * - Text files - * - Image files (PNG, JPEG, etc.) - * - PDF files + * The source URL of the content to preview for printing. Must be either a relative path appended to your app's [`application_url`](/docs/apps/build/cli-for-apps/app-configuration) or a full URL to your app's backend that returns the document. */ src: string; } diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/render/components/QRCode/QRCode.ts b/packages/ui-extensions/src/surfaces/point-of-sale/render/components/QRCode/QRCode.ts index 0afa1614ba..ef2ce0ef43 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/render/components/QRCode/QRCode.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/render/components/QRCode/QRCode.ts @@ -1,12 +1,8 @@ import {createRemoteComponent} from '@remote-ui/core'; -/** - * The `QRCode` component renders a QR code in Shopify POS. - * @property `value` the content to be encoded in the QR code. - */ export interface QRCodeProps { /** - * The content to be encoded in the QR code. + * The content to be encoded in the QR code. Can be any string such as a URL, email address, plain text, phone number, or formatted data. Specific string formatting can trigger actions on the user's device when scanned, like opening apps, preparing messages, or navigating to locations. */ value: string; } diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/render/components/RadioButtonList/RadioButtonList.ts b/packages/ui-extensions/src/surfaces/point-of-sale/render/components/RadioButtonList/RadioButtonList.ts index b5297ef417..a1dc1d1d03 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/render/components/RadioButtonList/RadioButtonList.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/render/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/render/components/Screen/Screen.ts b/packages/ui-extensions/src/surfaces/point-of-sale/render/components/Screen/Screen.ts index c0741893de..6316f4d768 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/render/components/Screen/Screen.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/render/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/render/components/SearchBar/SearchBar.ts b/packages/ui-extensions/src/surfaces/point-of-sale/render/components/SearchBar/SearchBar.ts index fd9bb754d1..cac09188a5 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/render/components/SearchBar/SearchBar.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/render/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/render/components/Section/Section.ts b/packages/ui-extensions/src/surfaces/point-of-sale/render/components/Section/Section.ts index 71055e0141..5317d65bd4 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/render/components/Section/Section.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/render/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/render/components/SectionHeader/SectionHeader.ts b/packages/ui-extensions/src/surfaces/point-of-sale/render/components/SectionHeader/SectionHeader.ts index 741d7cbb27..c7319f9ed5 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/render/components/SectionHeader/SectionHeader.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/render/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/render/components/SegmentedControl/SegmentedControl.ts b/packages/ui-extensions/src/surfaces/point-of-sale/render/components/SegmentedControl/SegmentedControl.ts index fde3c9f279..9fbd66c98a 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/render/components/SegmentedControl/SegmentedControl.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/render/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/render/components/Selectable/Selectable.ts b/packages/ui-extensions/src/surfaces/point-of-sale/render/components/Selectable/Selectable.ts index 601b2909bf..2163aa948a 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/render/components/Selectable/Selectable.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/render/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/render/components/Stack/Stack.ts b/packages/ui-extensions/src/surfaces/point-of-sale/render/components/Stack/Stack.ts index cdf9e8a7ea..959eaf4bb6 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/render/components/Stack/Stack.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/render/components/Stack/Stack.ts @@ -6,11 +6,13 @@ import { SpacingKeyword, GapProps, } from '../shared/inner-layouts'; +/* eslint-disable import/no-deprecated */ import { HorizontalSpacing, Spacing, VerticalSpacing, } from '../shared/deprecated-types'; +/* eslint-enable import/no-deprecated */ /** * @@ -20,8 +22,7 @@ type DeprecatedStackDirection = 'vertical' | 'horizontal'; export interface StackProps extends PaddingProps, SizingProps, GapProps { /** - * Sets how the Stack's children are placed within the Stack. - * 'vertical' and 'horizontal' are deprecated. Using these values will use the Stack implementation from 2024-10. + * The direction in which children are placed within the `Stack` component. Use `'block'` for vertical arrangement along the block axis without wrapping, or `'inline'` for horizontal arrangement along the inline axis with automatic wrapping. * * @default 'inline' */ @@ -36,85 +37,89 @@ export interface StackProps extends PaddingProps, SizingProps, GapProps { alignment?: ContentPosition | ContentDistribution; /** - * Aligns the Stack along the main axis. + * The alignment of the `Stack` component along the main axis, controlling how space is distributed between and around content items. + * Learn more about [justify-content on MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/justify-content). * - * @see https://developer.mozilla.org/en-US/docs/Web/CSS/justify-content * @default 'start' */ justifyContent?: ContentPosition | ContentDistribution; /** - * Aligns the Stack along the cross axis. + * The alignment of the `Stack` component along the cross axis, controlling how content is distributed when there's extra space. + * Learn more about [align-content on MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/align-content). * - * @see https://developer.mozilla.org/en-US/docs/Web/CSS/align-content * @default 'start' */ alignContent?: 'stretch' | ContentPosition | ContentDistribution; /** - * Aligns the Stack's children along the cross axis. + * The alignment of the `Stack` component's children along the cross axis, controlling how individual items are positioned. + * Learn more about [align-items on MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/align-items). * - * @see https://developer.mozilla.org/en-US/docs/Web/CSS/align-items * @default 'stretch' */ alignItems?: 'stretch' | 'baseline' | ContentPosition; /** - * The vertical padding around the stack. + * The vertical padding around the `Stack` component. + * * @deprecated Use the `paddingBlock` prop instead. */ + // eslint-disable-next-line import/no-deprecated paddingVertical?: VerticalSpacing; /** - * The horizontal padding around the stack. + * The horizontal padding around the `Stack` component. + * * @deprecated Use the `paddingInline` prop instead. */ + // eslint-disable-next-line import/no-deprecated paddingHorizontal?: HorizontalSpacing; /** - * The spacing between each child in the stack. + * The spacing between each child in the `Stack` component. + * * @defaultValue 1 * @deprecated Use the `gap` prop instead. */ + // eslint-disable-next-line import/no-deprecated spacing?: Spacing; /** - * The size of the gap between each child in the stack. + * The size of the gap between each child in the `Stack` component. + * * @defaultValue '0' */ gap?: SpacingKeyword; /** - * Adjust spacing between elements in the block axis. - * - * This overrides the row value of `gap`. + * The spacing between elements in the block axis. Overrides the row value of gap. * * @default '' - meaning no override */ rowGap?: SpacingKeyword | ''; /** - * Adjust spacing between elements in the inline axis. - * - * This overrides the column value of `gap`. + * The spacing between elements in the inline axis. Overrides the column value of gap. * * @default '' - meaning no override */ columnGap?: SpacingKeyword | ''; /** - * Whether the children should be stretched to fill the cross axis. + * A boolean that determines whether the children should be stretched to fill the cross axis. */ flexChildren?: boolean; /** - * The flex value for the stack. Flex 1 will stretch the stack to fill the parent. + * The flex value for the `Stack` component. A value of 1 will stretch the component to fill the parent container. */ flex?: number; /** - * Wrap behavior for the children of the stack. - * @deprecated Has no effect, content will always wrap. + * The wrap behavior for the children of the `Stack` component. + * + * @deprecated This property has no effect as content will always wrap. */ flexWrap?: 'wrap' | 'nowrap' | 'wrap-reverse'; } diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/render/components/Stepper/Stepper.ts b/packages/ui-extensions/src/surfaces/point-of-sale/render/components/Stepper/Stepper.ts index 064bf4ec16..7ba814a32e 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/render/components/Stepper/Stepper.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/render/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/render/components/Text/Text.ts b/packages/ui-extensions/src/surfaces/point-of-sale/render/components/Text/Text.ts index 013f74af3e..75867d8a33 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/render/components/Text/Text.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/render/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/render/components/TextArea/TextArea.ts b/packages/ui-extensions/src/surfaces/point-of-sale/render/components/TextArea/TextArea.ts index ffe4a8feaa..8a6b09bab6 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/render/components/TextArea/TextArea.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/render/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/render/components/TextField/TextField.ts b/packages/ui-extensions/src/surfaces/point-of-sale/render/components/TextField/TextField.ts index c93283a1d3..292bea353a 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/render/components/TextField/TextField.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/render/components/TextField/TextField.ts @@ -2,24 +2,54 @@ import {createRemoteComponent} from '@remote-ui/core'; 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/render/components/Tile/Tile.ts b/packages/ui-extensions/src/surfaces/point-of-sale/render/components/Tile/Tile.ts index 0a98f46127..ab693ddc33 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/render/components/Tile/Tile.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/render/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/render/components/TimeField/TimeField.ts b/packages/ui-extensions/src/surfaces/point-of-sale/render/components/TimeField/TimeField.ts index dd92aa3270..bbbfd48a35 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/render/components/TimeField/TimeField.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/render/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/render/components/TimePicker/TimePicker.ts b/packages/ui-extensions/src/surfaces/point-of-sale/render/components/TimePicker/TimePicker.ts index e692418482..369cdff932 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/render/components/TimePicker/TimePicker.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/render/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/render/components/shared/BaseTextField.ts b/packages/ui-extensions/src/surfaces/point-of-sale/render/components/shared/BaseTextField.ts index 93990ca973..111852a52a 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/render/components/shared/BaseTextField.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/render/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/render/components/shared/InputField.ts b/packages/ui-extensions/src/surfaces/point-of-sale/render/components/shared/InputField.ts index 040d809d23..b87d58c164 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/render/components/shared/InputField.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/render/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/render/components/shared/box.ts b/packages/ui-extensions/src/surfaces/point-of-sale/render/components/shared/box.ts index cc169b28a8..065b5837ab 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/render/components/shared/box.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/render/components/shared/box.ts @@ -1,129 +1,134 @@ import {SizeKeyword} from './sizes'; +/** + * Defines the available padding size options using numeric scale values. Provides precise control over spacing with predetermined size increments. + */ export type PaddingKeys = SizeKeyword | 'none'; export interface PaddingProps { /** - * Adjust the padding of all edges in pixels. + * Adjusts the padding on all edges of the box using predefined spacing values. * * @default '0' */ padding?: PaddingKeys; /** - * Adjust the block-padding. - * - * This overrides the block value of `padding`. + * Adjusts the padding on the block axis (vertical in horizontal writing modes). Overrides the block value from `padding`. * * @default '0' */ paddingBlock?: PaddingKeys; /** - * Adjust the block-start padding. - * - * This overrides the block-start value of `paddingBlock`. + * Adjusts the padding at the block-start edge (top in horizontal writing modes). Overrides the start value from `paddingBlock`. * * @default '0' */ paddingBlockStart?: PaddingKeys; /** - * Adjust the block-end padding. - * - * This overrides the block-end value of `paddingBlock`. + * Adjusts the padding at the block-end edge (bottom in horizontal writing modes). Overrides the end value from `paddingBlock`. * * @default '0' */ paddingBlockEnd?: PaddingKeys; /** - * Adjust the inline padding. - * - * - * This overrides the inline value of `padding`. + * Adjusts the padding on the inline axis (horizontal in horizontal writing modes). Overrides the inline value from `padding`. * * @default '0' */ paddingInline?: PaddingKeys; /** - * Adjust the inline-start padding. - * - * This overrides the inline-start value of `paddingInline`. + * Adjusts the padding at the inline-start edge (left in left-to-right languages). Overrides the start value from `paddingInline`. * * @default '0' */ paddingInlineStart?: PaddingKeys; /** - * Adjust the inline-end padding. + * Adjusts the padding at the inline-end edge (right in left-to-right languages). Overrides the end value from `paddingInline`. * - * This overrides the inline-end value of `paddingInline`. - * @default '0' */ paddingInlineEnd?: PaddingKeys; } +/** + * Defines exact size measurements without automatic or unconstrained options. Limited to specific pixel values, percentages, or zero. + * + * - `${number}px`: An exact pixel measurement for precise sizing that remains consistent across different contexts. + * - `${number}%`: A percentage-based size relative to the parent container for responsive sizing that adapts proportionally. + * - `'0'`: A zero size value that completely eliminates any dimension in that direction. + */ export type SizeUnits = `${number}px` | `${number}%` | `0`; + +/** + * Defines size values that can be specified as exact measurements or no constraint. Supports pixel values, percentages, zero, or no maximum limit. + * + * - `none`: An unconstrained size value that allows the element to grow without restriction, limited only by available space. + * - `${number}px`: An exact pixel measurement for precise sizing limits that remain consistent across different contexts. + * - `${number}%`: A percentage-based size relative to the parent container for responsive constraints that adapt to different screen sizes. + * - `'0'`: A zero size constraint that prevents the element from having any dimension in that direction. + */ export type SizeUnitsOrNone = SizeUnits | 'none'; + +/** + * Defines size values that can be specified as exact measurements or automatic sizing. Supports pixel values, percentages, zero, or automatic sizing based on content. + * + * - `auto`: An automatic sizing value that expands or contracts the element to fit its content while respecting size constraints. + * - `${number}px`: An exact pixel measurement for precise, fixed sizing that remains consistent across different contexts. + * - `${number}%`: A percentage-based size relative to the parent container for responsive layouts that adapt to different screen sizes. + * - `'0'`: A zero size value that completely collapses the element in that dimension. + */ export type SizeUnitsOrAuto = SizeUnits | 'auto'; export interface SizingProps { /** - * Adjust the block size. - * - * Auto takes the block size of the box's children. - * - * @see https://developer.mozilla.org/en-US/docs/Web/CSS/block-size + * Adjusts the block size (height in horizontal writing modes). Use `'auto'` to take the block size of the box's children. + * Learn more about [block-size on MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/block-size). * * @default 'auto' */ blockSize?: SizeUnitsOrAuto; /** - * Adjust the minimum block size. - * - * @see https://developer.mozilla.org/en-US/docs/Web/CSS/min-block-size + * Adjusts the minimum block size (min-height in horizontal writing modes). + * Learn more about [min-block-size on MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/min-block-size). * * @default '0' */ minBlockSize?: SizeUnits; /** - * Adjust the maximum block size. - * - * @see https://developer.mozilla.org/en-US/docs/Web/CSS/max-block-size + * Adjusts the maximum block size (max-height in horizontal writing modes). + * Learn more about [max-block-size on MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/max-block-size). * * @default 'none' */ maxBlockSize?: SizeUnitsOrNone; /** - * Adjust the inline size. - * - * Auto takes the inline size of the box's children. - * - * @see https://developer.mozilla.org/en-US/docs/Web/CSS/inline-size + * Adjusts the inline size (width in horizontal writing modes). Use `'auto'` to take the inline size of the box's children. + * Learn more about [inline-size on MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/inline-size). * * @default 'auto' */ inlineSize?: SizeUnitsOrAuto; /** - * Adjust the minimum inline size. - * - * @see https://developer.mozilla.org/en-US/docs/Web/CSS/min-inline-size + * Adjusts the minimum inline size (min-width in horizontal writing modes). + * Learn more about [min-inline-size on MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/min-inline-size). * * @default '0' */ minInlineSize?: SizeUnits; /** - * Adjust the maximum inline size. - * - * @see https://developer.mozilla.org/en-US/docs/Web/CSS/max-inline-size + * Adjusts the maximum inline size (max-width in horizontal writing modes). + * Learn more about [max-inline-size on MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/max-inline-size). * * @default 'none' */ diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/render/components/shared/deprecated-types.ts b/packages/ui-extensions/src/surfaces/point-of-sale/render/components/shared/deprecated-types.ts index be3382bf24..085ebd1fd2 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/render/components/shared/deprecated-types.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/render/components/shared/deprecated-types.ts @@ -1,3 +1,7 @@ +/** + * Deprecated spacing values represented as numeric multipliers. + * @deprecated Use `SizeKeyword` from `./sizes` instead for consistent spacing across the design system. + */ export type Spacing = | 0.5 | 1 @@ -14,6 +18,10 @@ export type Spacing = | 13 | 16; +/** + * Deprecated vertical spacing values using named size keywords. + * @deprecated Use `SizeKeyword` from `./sizes` instead for consistent spacing across the design system. + */ export type VerticalSpacing = | 'HalfPoint' | 'ExtraSmall' @@ -22,6 +30,10 @@ export type VerticalSpacing = | 'Large' | 'ExtraLarge'; +/** + * Deprecated horizontal spacing values using named size keywords. + * @deprecated Use `SizeKeyword` from `./sizes` instead for consistent spacing across the design system. + */ export type HorizontalSpacing = | 'HalfPoint' | 'ExtraSmall' diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/render/components/shared/inner-layouts.ts b/packages/ui-extensions/src/surfaces/point-of-sale/render/components/shared/inner-layouts.ts index 4689d17ba1..69783ff789 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/render/components/shared/inner-layouts.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/render/components/shared/inner-layouts.ts @@ -1,34 +1,41 @@ import {SizeKeyword} from './sizes'; +/** + * Spacing values that can be used for gaps between elements, including all size keywords and `'none'` for no spacing. + */ export type SpacingKeyword = SizeKeyword | 'none'; export interface GapProps { /** - * Adjust spacing between elements. + * Adjusts the spacing between child elements on both axes using predefined spacing values. + * * @default 'none' */ gap?: SpacingKeyword; /** - * Adjust spacing between elements in the block axis. - * - * This overrides the row value of `gap`. + * Adjusts the spacing between elements in the block axis (vertical spacing in horizontal writing modes). Overrides the row value from `gap`. * * @default '' - meaning no override */ rowGap?: SpacingKeyword | ''; /** - * Adjust spacing between elements in the inline axis. - * - * This overrides the column value of `gap`. + * Adjusts the spacing between elements in the inline axis (horizontal spacing in horizontal writing modes). Overrides the column value from `gap`. * * @default '' - meaning no override */ columnGap?: SpacingKeyword | ''; } +/** + * Defines positioning values for aligning content within a container. + */ export type ContentPosition = 'center' | 'start' | 'end'; + +/** + * Defines distribution strategies for spacing content within a container. + */ export type ContentDistribution = | 'space-around' | 'space-between' diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/render/components/shared/sizes.ts b/packages/ui-extensions/src/surfaces/point-of-sale/render/components/shared/sizes.ts index 91bb80510d..de79ece0ad 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/render/components/shared/sizes.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/render/components/shared/sizes.ts @@ -1,5 +1,7 @@ /** - * SizeKeyword maps to predetermined values in POS. + * Defines the standardized spacing scale used throughout the POS design system. Each keyword maps to a predetermined + * spacing value that ensures visual consistency across components. Values range from `'0'` (no spacing) through `'2000'` + * (maximum spacing), with increments designed to create harmonious visual rhythm and hierarchy. */ export type SizeKeyword = | '0' 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 75d2a0ef3c..1e2c70186f 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/targets.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/targets.ts @@ -38,28 +38,116 @@ 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< StandardApi<'pos.home.tile.render'> & 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 & diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/types/base-transaction-complete.ts b/packages/ui-extensions/src/surfaces/point-of-sale/types/base-transaction-complete.ts index 369645b4c0..d09b8028d4 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/types/base-transaction-complete.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/types/base-transaction-complete.ts @@ -5,16 +5,56 @@ import type {ShippingLine} from './shipping-line'; import type {TaxLine} from './tax-line'; import type {TransactionType} from './transaction-type'; +/** + * Base interface for completed transaction data shared across all transaction types. + */ export interface BaseTransactionComplete { + /** + * The transaction type identifier indicating which kind of transaction was completed (for example, `'Sale'` for new purchases, `'Return'` for refunds, `'Exchange'` for item swaps, `'Reprint'` for receipt reprints). This determines the transaction's business logic, receipt format, and inventory impact. + */ transactionType: TransactionType; + /** + * The unique numeric identifier for the Shopify order created by this transaction. This ID links the POS transaction to the order record in Shopify's system and can be used for order lookups, tracking, and API operations. Returns `undefined` for transactions that don't create orders (for example, reprints) or when order creation is pending. + */ orderId?: number; + /** + * The customer information if this transaction is associated with a customer account. Contains the customer ID for linking to customer records. Returns `undefined` for guest transactions where no customer was selected or when the transaction doesn't support customer association. + */ customer?: Customer; + /** + * An array of all discounts applied to this transaction, including cart-level discounts, automatic discounts, and discount codes. Each discount entry contains the discount amount, type, and description. Returns `undefined` or empty array when no discounts were applied. The sum of discount amounts reduces the final transaction total. + */ discounts?: Discount[]; + /** + * The total tax amount charged on this transaction as a `Money` object. This is the sum of all tax lines and represents the combined tax from all applicable tax jurisdictions and rules. Tax calculations are based on the location, products, customer, and tax settings configured in Shopify. + */ taxTotal: Money; + /** + * The subtotal amount before taxes and after discounts are applied, as a `Money` object. This represents the sum of all line item prices (quantity × unit price) minus any discounts, but before tax is added. This is the taxable base amount for most tax calculations. + */ subtotal: Money; + /** + * The final total amount the customer pays for this transaction as a `Money` object. This includes all line items, shipping charges, taxes, and accounts for all discounts. This is the amount that must be tendered through payment methods. Calculated as: subtotal + taxTotal + shipping - discounts. + */ grandTotal: Money; + /** + * An array of all payment methods used to complete this transaction. Each payment entry specifies the payment type (for example, cash, credit card), amount tendered, and currency. Multiple entries indicate split payments where the customer paid using multiple methods (for example, part cash, part credit card). The sum of all payment amounts should equal or exceed the `grandTotal`. + */ paymentMethods: Payment[]; + /** + * The remaining balance still owed on this transaction as a `Money` object. Typically `{amount: 0, currency: "USD"}` for fully paid transactions. A positive balance indicates partial payment or layaway scenarios. A negative balance indicates overpayment, where change should be returned to the customer. Calculated as: grandTotal minus sum of all payment amounts. + */ balanceDue: Money; + /** + * An array of shipping charges applied to this transaction. Each shipping line represents a shipping method with its price and associated taxes. Multiple entries can exist when different shipping methods apply to different items or when combining shipping with pickup. Returns `undefined` or empty array for transactions with no shipping charges (for example, in-store purchases, digital products). + */ shippingLines?: ShippingLine[]; + /** + * An array of individual tax lines showing the detailed tax breakdown by jurisdiction and tax type. Each tax line represents a specific tax (for example, state tax, federal tax, VAT, GST) with its rate and calculated amount. Multiple tax lines can apply to a single transaction based on location, product taxability, and tax rules. Returns `undefined` or empty array for tax-exempt transactions or when detailed tax breakdown isn't available. + */ taxLines?: TaxLine[]; + /** + * The [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp when the transaction was executed and completed (for example, `"2024-05-15T14:30:00Z"`). This marks the exact moment the transaction was finalized, payment was processed, and the order was created. Commonly used for transaction history, chronological sorting, reporting, audit trails, and synchronization with external systems. + */ + executedAt: string; } diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/types/cart.ts b/packages/ui-extensions/src/surfaces/point-of-sale/types/cart.ts index 3a1788594e..6a49413390 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/types/cart.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/types/cart.ts @@ -1,85 +1,290 @@ import {CountryCode} from './country-code'; import {TaxLine} from './tax-line'; +/** + * 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 { + /** + * Indicates whether the cart is currently editable. An `undefined` value should be treated as `true` for backward compatibility. Use this to determine if cart modification operations are allowed. + */ + editable?: boolean; + /** + * 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 to apply to the line item. Merged with existing properties—duplicate keys overwrite existing values. + */ properties: Record; } +/** + * Specifies the parameters for updating cart information. Includes options for modifying customer data, notes, references, and other cart-level metadata. + */ export interface CartUpdateInput { + /** + * 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 to apply to the line item. Merged with existing properties—duplicate keys overwrite existing values. + */ 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; } +/** + * 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 identifier for this line item within the cart. Use for line item-specific operations like updates, removals, or property modifications. + */ uuid: string; + /** + * The unit price of the line item. Returns 'undefined' for custom sales without set prices. Use for pricing calculations and displays. + */ price?: number; + /** + * The quantity of this item in the cart. Always a positive integer. Use for quantity displays, calculations, and inventory management. + */ quantity: number; + /** + * The display title of the line item. Returns 'undefined' for items without titles. Use for customer-facing displays and cart item identification. + */ title?: string; + /** + * The product variant 'ID' this line item represents. Returns 'undefined' for custom sales or non-variant items. Use for variant-specific operations and product details. + */ variantId?: number; + /** + * The product 'ID' this line item represents. Returns 'undefined' for custom sales or non-product items. Use for product-specific operations and linking to product details. + */ productId?: number; + /** + * An array of discounts applied to this line item. Empty array if no discounts are active. Use for displaying line item savings and discount details. + */ discounts: Discount[]; + /** + * An array of discount allocations applied to this line item, providing detailed breakdown of how discounts are distributed. Returns 'undefined' if no allocations exist. Use for enhanced discount tracking and reporting. + */ + discountAllocations?: Discount[]; + /** + * Determines whether this line item is subject to tax calculations. Use for tax computation, compliance, and pricing displays. + */ taxable: boolean; + /** + * An array of tax lines applied to this line item, containing tax amounts and rates. Use for detailed tax reporting and compliance. + */ taxLines: TaxLine[]; + /** + * The Stock Keeping Unit (SKU) identifier for this line item. Returns 'undefined' if no SKU is configured. Use for inventory tracking and product identification. + */ sku?: string; + /** + * The vendor or brand name for this line item. Returns 'undefined' if no vendor is set. Use for vendor-specific displays and organization. + */ vendor?: string; + /** + * The custom key-value properties attached to this line item. Empty object if no properties are set. Use for metadata, customization options, or integration data. + */ properties: {[key: string]: string}; + /** + * Determines whether this line item is a gift card. Gift cards have special handling requirements and business logic. Use for implementing gift card-specific workflows. + */ isGiftCard: boolean; + /** + * The staff member 'ID' attributed to this line item. Returns 'undefined' if no staff attribution is set. Use for commission tracking and performance analytics. + */ attributedUserId?: number; + /** + * Determines whether this line item requires a selling plan (subscription) to be purchased. Returns 'undefined' if selling plan information is unavailable. Use for implementing subscription-based product handling. + */ + requiresSellingPlan?: boolean; + /** + * Determines whether this line item has selling plan groups (subscription options) available. Returns 'undefined' if selling plan information is unavailable. Use for displaying subscription options. + */ + hasSellingPlanGroups?: boolean; + /** + * The currently selected selling plan for this line item. Returns 'undefined' if no selling plan is applied. Contains selling plan details including 'ID', name, and delivery intervals. Use for subscription management and recurring purchase functionality. + */ + sellingPlan?: SellingPlan; + /** + * Bundle components for this line item. Only present for [product bundles](/docs/apps/build/product-merchandising/bundles). Each component represents an individual item within the bundle with its own tax information. + */ + components?: LineItemComponent[]; } +/** + * Represents a component of a [product bundle](/docs/apps/build/product-merchandising/bundles) line item. Bundle components contain the individual items that make up a bundle, each with their own pricing and tax information. + */ +export interface LineItemComponent { + /** + * The display name for the custom sale item. Appears on receipts and in cart displays. Should be descriptive and customer-friendly. + */ + title?: string; + /** + * The quantity of the custom sale item. Must be a positive integer. Use for quantity-based pricing and inventory management. + */ + quantity: number; + /** + * The price for the custom sale item as currency string. Must be a valid positive amount. Use for non-catalog items and custom pricing. + */ + price?: number; + /** + * Determines whether the custom sale item is taxable. Set to `true` to apply tax calculations, `false` to exempt from taxes. + */ + taxable: boolean; + /** + * An array of tax lines applied to this component. + */ + taxLines: TaxLine[]; + /** + * The unique numeric identifier for the product variant this component represents, if applicable. + */ + variantId?: number; + /** + * The unique numeric identifier for the product this component represents, if applicable. + */ + productId?: number; +} + +/** + * Represents a selling plan (subscription) associated with a line item, containing delivery schedule and plan identification details. + */ +export interface SellingPlan { + /** + * The unique identifier of the selling plan. + */ + id: number; + /** + * The name of the POS device. + */ + name: string; + /** + * The fingerprint of the applied selling plan within this cart session. Provided by POS. Not available during refund / exchanges. + */ + digest?: string; + /** + * The interval of the selling plan. (DAY, WEEK, MONTH, YEAR). + */ + deliveryInterval?: string; + /** + * The number of intervals between deliveries. + */ + deliveryIntervalCount?: number; +} + +/** + * 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; + /** + * The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code associated with the location currently active on POS. + */ + currency?: string; + /** + * 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.shopify.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 target line item `UUID` for selling plan assignment. Must match an existing line item in the cart. */ lineItemUuid: string; /** - * The custom properties to apply to the line item. + * The custom key-value properties to apply to the line item. Merged with existing properties—duplicate keys overwrite existing values. */ 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 target line item `UUID` for selling plan assignment. Must match an existing line item in the cart. */ 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 display name for the custom sale item. Appears on receipts and in cart displays. Should be descriptive and customer-friendly. */ title: string; /** @@ -92,25 +297,100 @@ export interface LineItemDiscount { amount: string; } +/** + * Represents a custom sale item that is not associated with a product in the catalog. Includes pricing, taxation, and descriptive information for manually created line items. + */ export interface CustomSale { + /** + * The quantity of the custom sale item. Must be a positive integer. Use for quantity-based pricing and inventory management. + */ quantity: number; + /** + * The display name for the custom sale item. Appears on receipts and in cart displays. Should be descriptive and customer-friendly. + */ title: string; + /** + * The price for the custom sale item as currency string. Must be a valid positive amount. Use for non-catalog items and custom pricing. + */ price: string; + /** + * Determines whether the custom sale item is taxable. Set to `true` to apply tax calculations, `false` to exempt from taxes. + */ 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. Required for most shipping and billing operations. Should contain street number and name. + */ address1?: string; + /** + * The secondary address line for apartment, suite, or unit information. Optional field for additional address details. + */ address2?: string; + /** + * The city name for the address. Required for shipping calculations and location-based services. + */ city?: string; + /** + * The company name associated with the address. Optional field for business customers and B2B transactions. + */ company?: string; + /** + * The first name for the address contact. Used for personalized shipping labels and customer communication. + */ firstName?: string; + /** + * The last name for the address contact. Required for complete customer identification and shipping labels. + */ lastName?: string; + /** + * The phone number for the address contact. Used for delivery notifications, shipping updates, and customer communication. + */ phone?: string; + /** + * The province or state name for the address. Required for regional shipping rates and tax calculations. + */ province?: string; + /** + * The country name for the address. Required for international shipping, tax calculations, and compliance. + */ country?: string; + /** + * The postal or ZIP code for the address. Required for accurate shipping rates and location-based services. + */ zip?: string; + /** + * The full name for the address contact. Use when first and last names are combined or unavailable as separate fields. + */ name?: string; + /** + * The standardized province or state code. Use for precise regional identification and automated shipping calculations. + */ provinceCode?: string; + /** + * The standardized country code (ISO format). Use for precise country identification and international shipping operations. + */ countryCode?: CountryCode; } + +/** + * Specifies the parameters for assigning selling plans to line items. Used to add subscription or purchase option configurations to products. + */ +export interface SetLineItemSellingPlanInput { + /** + * The target line item `UUID` for selling plan assignment. Must match an existing line item in the cart. + */ + lineItemUuid: string; + /** + * The selling plan `ID` to apply to the line item. Must be a valid selling plan available for the product. + */ + sellingPlanId: number; + /** + * The selling plan name for display purposes. Required for proper selling plan display in the cart. + */ + sellingPlanName?: string; +} diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/types/country-code.ts b/packages/ui-extensions/src/surfaces/point-of-sale/types/country-code.ts index 66d11a842e..36ca7a8fe6 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/types/country-code.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/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/types/device.ts b/packages/ui-extensions/src/surfaces/point-of-sale/types/device.ts index 800c81eb95..b69f1e203c 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/types/device.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/types/device.ts @@ -1,14 +1,17 @@ +/** + * Defines information about the POS device where the extension is running. + */ export interface Device { /** - * The name of the device + * The name of the POS device. */ name: string; /** - * The ID of the device + * The unique identifier for the POS device. */ deviceId: number; /** - * Whether the device is a tablet + * Whether the device is a tablet form factor. */ isTablet: boolean; } diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/types/money.ts b/packages/ui-extensions/src/surfaces/point-of-sale/types/money.ts index 84a72623a9..127d802fce 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/types/money.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/types/money.ts @@ -1,4 +1,27 @@ +/** + * Represents a monetary amount with currency information. + */ export interface Money { + /** + * The monetary amount as a number. + */ amount: number; + /** + * The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code associated with the location currently active on POS. + */ currency: string; } + +/** + * Represents a monetary amount as a string with explicit currency code. + */ +export interface MoneyV2 { + /** + * The monetary amount as a string. + */ + amount: string; + /** + * The ISO currency code (for example, USD, CAD). + */ + currencyCode: string; +} diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/types/multiple-resource-result.ts b/packages/ui-extensions/src/surfaces/point-of-sale/types/multiple-resource-result.ts index 61749a5d0e..06fa71539d 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/types/multiple-resource-result.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/types/multiple-resource-result.ts @@ -1,6 +1,5 @@ /** - * 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 { /** diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/types/paginated-result.ts b/packages/ui-extensions/src/surfaces/point-of-sale/types/paginated-result.ts index f222c7e268..baa50cfce2 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/types/paginated-result.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/types/paginated-result.ts @@ -1,5 +1,5 @@ /** - * 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 { /** @@ -8,8 +8,7 @@ export interface PaginatedResult { 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; diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/types/payment.ts b/packages/ui-extensions/src/surfaces/point-of-sale/types/payment.ts index b851d8d4b5..0a8edc23e1 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/types/payment.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/types/payment.ts @@ -1,3 +1,6 @@ +/** + * The available payment method types for POS transactions. + */ export type PaymentMethod = | 'Cash' | 'Custom' @@ -9,8 +12,21 @@ export type PaymentMethod = | 'ShopPay' | 'StoreCredit' | 'Unknown'; + +/** + * Represents a payment applied to a transaction, including the amount, currency, and payment method type. + */ export interface Payment { + /** + * The payment amount. + */ amount: number; + /** + * The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code associated with the location currently active on POS. + */ currency: string; + /** + * The payment method type. + */ type: PaymentMethod; } diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/types/product.ts b/packages/ui-extensions/src/surfaces/point-of-sale/types/product.ts index 74493566cb..d30e00d210 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/types/product.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/types/product.ts @@ -1,62 +1,234 @@ +/** + * 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; + /** + * Indicates whether this product or line item requires a selling plan (subscription) to be purchased. When `true`, the customer must select a subscription or payment plan before adding to cart. When `false`, the item can be purchased as a one-time purchase without a selling plan. + */ + requiresSellingPlan?: boolean; + /** + * Indicates whether this product or line item has selling plan groups (subscription options) available. When `true`, the product offers subscription or recurring payment options that customers can select. When `false`, the product is only available for one-time purchase without subscription options. + */ + hasSellingPlanGroups?: boolean; } +/** + * 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/types/session.ts b/packages/ui-extensions/src/surfaces/point-of-sale/types/session.ts index 2b730304cb..f5be123a06 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/types/session.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/types/session.ts @@ -1,5 +1,8 @@ import type {CurrencyCode} from '../../../shared'; +/** + * Defines information about the current POS session. + */ export interface Session { /** * The shop ID associated with the shop currently logged into POS. @@ -17,18 +20,22 @@ export interface Session { shopDomain: string; /** - * The location ID associated with the POS' current location. + * The location ID associated with the POS device's current location. */ 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 staff ID of the staff member currently pinned into the POS. This may differ from the user ID if the pinned staff member is different from the logged-in user. */ staffMemberId?: number; /** - * The currency code associated with the location currently in on POS. + * The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code associated with the location currently active on POS. */ currency: CurrencyCode; + + /** + * The version of [the POS app](https://apps.shopify.com/shopify-pos) currently running. + */ + posVersion: string; } diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/types/shipping-line.ts b/packages/ui-extensions/src/surfaces/point-of-sale/types/shipping-line.ts index d7bf636852..8b9b5759c2 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/types/shipping-line.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/types/shipping-line.ts @@ -1,16 +1,50 @@ import type {Money} from './money'; +import type {TaxLine} from './tax-line'; +/** + * Represents a shipping charge applied to an order, including the price and applicable taxes. + */ export interface ShippingLine { + /** + * The handle identifier for the shipping method. + */ handle?: string; + /** + * The price of the shipping as a Money object. + */ price: Money; + /** + * The display title of the shipping method. + */ title?: string; + /** + * An array of individual tax lines showing tax breakdown. + */ + taxLines?: TaxLine[]; } +/** + * Represents a calculated shipping line with specific shipping or retail method type. + */ export interface CalculatedShippingLine extends ShippingLine { + /** + * The type identifier for calculated shipping. This is always `'Calculated'` to distinguish from custom shipping lines. Calculated shipping rates are determined by carrier APIs, zone-based rules, or automated shipping calculators. + */ type: 'Calculated'; + /** + * The shipping method category indicating whether this is standard shipping delivery or in-store retail pickup: + * - `'SHIPPING'`: Traditional carrier-based shipping where items are delivered to a customer address. + * - `'RETAIL'`: In-store pickup or buy-online-pickup-in-store (BOPIS) where customers collect items at a physical location. + */ methodType: 'SHIPPING' | 'RETAIL'; } +/** + * Represents a custom shipping line with merchant-defined shipping charges. + */ export interface CustomShippingLine extends ShippingLine { + /** + * The type identifier for custom shipping. This is always `'Custom'` to distinguish from calculated shipping lines. Custom shipping rates are manually set by merchants rather than calculated by carrier APIs or automated systems. + */ type: 'Custom'; } diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/types/tax-line.ts b/packages/ui-extensions/src/surfaces/point-of-sale/types/tax-line.ts index 50085b6eac..252f17a985 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/types/tax-line.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/types/tax-line.ts @@ -1,10 +1,31 @@ import type {Money} from './money'; +/** + * Represents a tax line applied to an item or transaction. + */ export interface TaxLine { + /** + * The title or name of the tax. + */ title: string; + /** + * The tax amount as a Money object. + */ price: Money; + /** + * The tax rate as a decimal number. + */ rate: number; + /** + * The unique identifier for this tax line. + */ uuid?: string; + /** + * The range of tax rates if applicable. + */ rateRange?: {min: number; max: number}; + /** + * Whether this tax is currently enabled. + */ enabled?: boolean; } diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/types/transaction-type.ts b/packages/ui-extensions/src/surfaces/point-of-sale/types/transaction-type.ts index b503527655..8461e888ec 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/types/transaction-type.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/types/transaction-type.ts @@ -1 +1,8 @@ +/** + * The types of transactions that can be processed in POS: + * - `'Sale'`: A new sale transaction where a customer purchases products or services. This creates a new order and processes payment. The most common transaction type in POS operations. + * - `'Return'`: A return transaction where a customer returns previously purchased items for a refund. This credits back payment to the customer and returns items to inventory. + * - `'Exchange'`: An exchange transaction where a customer returns items and simultaneously purchases replacement items. This combines return and sale operations in a single transaction, often with a price adjustment. + * - `'Reprint'`: A receipt reprint operation where an existing transaction's receipt is reprinted. No new transaction is created—this only regenerates the receipt document for an existing sale, return, or exchange. + */ export type TransactionType = 'Sale' | 'Return' | 'Exchange' | 'Reprint';