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 5afc5a6039..c3be074c81 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,47 +7,58 @@ const generateJsxCodeBlockForActionApi = (title: string, fileName: string) => const data: ReferenceEntityTemplateSchema = { name: 'Action API', - description: ` -The Action API allows an action extension to modally present its corresponding modal target. - -#### Supporting targets -- ${TargetLink.PosHomeTileRender} -- ${TargetLink.PosPurchasePostActionMenuItemRender} -- ${TargetLink.PosPurchasePostBlockRender} -- ${TargetLink.PosOrderDetailsActionMenuItemRender} -- ${TargetLink.PosOrderDetailsBlockRender} -- ${TargetLink.PosProductDetailsActionMenuItemRender} -- ${TargetLink.PosProductDetailsBlockRender} -- ${TargetLink.PosCustomerDetailsActionMenuItemRender} -- ${TargetLink.PosCustomerDetailsBlockRender} -- ${TargetLink.PosDraftOrderDetailsActionMenuItemRender} -- ${TargetLink.PosDraftOrderDetailsBlockRender} -`, + description: + 'The Action API provides modal presentation functionality for POS UI extensions, allowing you to launch full-screen modal interfaces from menu items, tiles, and block targets. The API enables navigation between different targets within your extension.', isVisualComponent: false, type: 'APIs', definitions: [ { title: 'ActionApi', - description: '', + description: + 'The `ActionApi` object provides methods for presenting modal interfaces. Access these methods through `shopify.action` to launch full-screen modal experiences.', type: 'ActionApiContent', }, ], - category: 'APIs', + category: 'Target APIs', + subCategory: 'Standard APIs', related: [], + subSections: [ + { + type: 'Generic', + anchorLink: 'best-practices', + title: 'Best practices', + sectionContent: + "- **Use modals for complex workflows:** Reserve modals for operations that genuinely require more screen space, multiple steps, or complex interactions that can't be handled by simple button actions.\n" + + '- **Provide clear entry points:** Use descriptive button labels and titles that clearly indicate what the modal will contain or what action it will perform, helping users understand what to expect.\n' + + '- **Handle modal dismissal gracefully:** Ensure your modal-based workflows handle user dismissal, saving progress when possible and providing clear feedback about incomplete operations.', + }, + { + 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.', + }, + ], 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: generateJsxCodeBlockForActionApi( - '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: generateJsxCodeBlockForActionApi( - '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.", }, ], }, 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 50c5b42db3..0e804f0c76 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,194 +7,254 @@ const generateJsxCodeBlockForCartApi = (title: string, fileName: string) => const data: ReferenceEntityTemplateSchema = { name: 'Cart API', - description: ` -The Cart API enables UI Extensions to manage and interact with POS cart contents, such as discounts, line items, and customer details. It provides a comprehensive set of functions for adding and removing items, alongside a subscribable object that keeps the UI Extension updated with real-time changes to the cart. - -#### Supporting targets -- ${TargetLink.PosHomeTileRender} -- ${TargetLink.PosHomeModalRender} -- ${TargetLink.PosProductDetailsActionMenuItemRender} -- ${TargetLink.PosProductDetailsActionRender} -- ${TargetLink.PosProductDetailsBlockRender} -- ${TargetLink.PosCustomerDetailsActionMenuItemRender} -- ${TargetLink.PosCustomerDetailsActionRender} -- ${TargetLink.PosCustomerDetailsBlockRender} -- ${TargetLink.PosOrderDetailsActionMenuItemRender} -- ${TargetLink.PosOrderDetailsActionRender} -- ${TargetLink.PosOrderDetailsBlockRender} -- ${TargetLink.PosDraftOrderDetailsActionMenuItemRender} -- ${TargetLink.PosDraftOrderDetailsActionRender} -- ${TargetLink.PosDraftOrderDetailsBlockRender} -`, + description: + 'The Cart API provides comprehensive access to POS cart management functionality, enabling extensions to read cart state, modify line items, apply discounts, manage customer information, and handle cart properties. The API supports both individual and bulk operations for efficient cart manipulation, with [selling plan functionality](/docs/apps/build/purchase-options/subscriptions/selling-plans) and error handling.', isVisualComponent: false, type: 'APIs', definitions: [ { title: 'CartApi', - description: '', + description: + 'The `CartApi` object provides access to cart management functionality and real-time cart state monitoring. Access these properties through `shopify.cart` to interact with the current POS cart.', type: 'CartApiContent', }, ], - category: 'APIs', + category: 'Target APIs', + subCategory: 'Contextual APIs', related: [], + subSections: [ + { + type: 'Generic', + anchorLink: 'best-practices', + title: 'Best practices', + sectionContent: + '- **Handle cart state reactively:** Use the signal-based interface to automatically update your extension UI when cart changes occur.\n' + + '- **Validate operations before execution:** Check cart editability and validate input data before performing cart operations to prevent errors.\n' + + '- **Use bulk operations for efficiency:** When performing multiple related operations, use bulk methods like `bulkCartUpdate`, `bulkSetLineItemDiscounts`, and `bulkAddLineItemProperties` for better performance and reduced API calls.\n' + + '- **Handle errors gracefully:** Implement proper error handling for all cart operations, as they may fail due to inventory constraints, validation errors, oversell protection, or business rule violations.\n' + + '- **Manage selling plans appropriately:** When working with subscription products, validate selling plan compatibility and handle selling plan requirements.', + }, + { + type: 'Generic', + anchorLink: 'limitations', + title: 'Limitations', + sectionContent: + '- Cart operations may fail due to business rules, inventory constraints, oversell protection, or validation errors—always implement appropriate error handling.\n' + + '- Some operations require specific preconditions. For example, customer must be present for address operations and selling plans must be compatible with line items.\n' + + '- Selling plan operations are only available for products that support selling plans and may have additional validation requirements.', + }, + ], 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: generateJsxCodeBlockForCartApi( - 'Subscribe to cart changes.', - 'subscribe', + '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: generateJsxCodeBlockForCartApi( - 'Check editable state of the cart', - 'check-cart-editable', + '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: generateJsxCodeBlockForCartApi( - 'Apply a cart level discount', - 'apply-cart-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: generateJsxCodeBlockForCartApi( - 'Apply a cart level discount code', - 'apply-cart-code-discount', + 'Add a subscription selling plan to a line item', + 'add-line-item-selling-plan', ), + description: + 'Attach a selling plan to a line item to enable subscription or recurring payment options. This example demonstrates using `addLineItemSellingPlan()` to add a subscription plan to a specific product, allowing customers to purchase items on a recurring basis.', }, { codeblock: generateJsxCodeBlockForCartApi( - '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: generateJsxCodeBlockForCartApi( - '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: generateJsxCodeBlockForCartApi( - '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: generateJsxCodeBlockForCartApi( - '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: generateJsxCodeBlockForCartApi( - '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: generateJsxCodeBlockForCartApi( - '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: generateJsxCodeBlockForCartApi( - '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: generateJsxCodeBlockForCartApi( - '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: generateJsxCodeBlockForCartApi( - '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: generateJsxCodeBlockForCartApi( - '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: generateJsxCodeBlockForCartApi( - 'Add custom properties to the cart', - 'add-cart-properties', + 'Check if the cart is editable', + 'check-cart-editable', ), + description: + 'Check whether the cart can be modified before attempting cart operations. This example demonstrates using `cart.editable` to verify editability, preventing errors from operations attempted on locked or finalized carts during payment processing or order completion.', }, { codeblock: generateJsxCodeBlockForCartApi( - 'Remove custom properties from the cart', - 'remove-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: generateJsxCodeBlockForCartApi( - 'Add custom properties to a line item', - 'add-line-item-properties', + 'Delete a customer address', + 'delete-address', ), + description: + "Remove an address from the customer's profile using its address ID. This example demonstrates using `deleteAddress()` to permanently delete an address, which is useful for maintaining accurate customer records and removing outdated or incorrect addresses.", }, { codeblock: generateJsxCodeBlockForCartApi( - 'Add custom properties to multiple line items', - 'bulk-add-line-item-properties', + 'Monitor cart changes in real time', + 'subscribe', ), + description: + 'Subscribe to cart state changes to build reactive UI components that automatically update when the cart is modified. This example shows how to use the `cart.subscribe()` method to receive real-time notifications whenever line items, discounts, customer information, or other cart properties change.', }, { codeblock: generateJsxCodeBlockForCartApi( - 'Remove custom properties from a line item', - 'remove-line-item-properties', + 'Remove a discount from a line item', + 'remove-line-item-discount', ), + description: + 'Remove a discount from a specific line item using its UUID. This example demonstrates using `removeLineItemDiscount()` to clear the discount from a particular item, restoring it to its standard price while leaving other cart discounts intact.', }, { codeblock: generateJsxCodeBlockForCartApi( - 'Set an attributed staff member on the cart', - 'set-attributed-staff', + 'Remove a product from the cart', + 'remove-line-item', ), + description: + 'Remove a specific line item from the cart using its UUID. This example demonstrates using `removeLineItem()` to delete an item from the cart, including any associated discounts or properties on that item.', }, { codeblock: generateJsxCodeBlockForCartApi( - 'Set an attributed staff member on a line item', - 'set-attributed-staff-to-line-item', + 'Remove a subscription selling plan from a line item', + 'remove-line-item-selling-plan', ), + description: + 'Remove the selling plan from a line item to convert it back to a one-time purchase. This example shows how to use `removeLineItemSellingPlan()` to clear subscription settings from a specific item while keeping the item in the cart.', }, { codeblock: generateJsxCodeBlockForCartApi( - 'Add an address to the customer in the cart', - 'add-address', + 'Remove all discounts from the cart and line items', + 'remove-all-discounts', ), + description: + 'Clear all discounts from the cart and its line items in a single operation. This example uses `removeAllDiscounts()` to remove cart-level discounts, line item discounts, and any applied discount codes, resetting pricing to standard amounts.', }, { codeblock: generateJsxCodeBlockForCartApi( - 'Delete an address corresponding to an ID', - 'delete-address', + 'Remove custom properties from a line item', + 'remove-line-item-properties', ), + description: + 'Remove specific custom properties from a line item by providing its UUID and an array of property keys to delete. This example demonstrates using `removeLineItemProperties()` to clear particular metadata fields from an item while keeping other properties intact.', }, { codeblock: generateJsxCodeBlockForCartApi( - 'Set the default address of the customer in the cart', - 'update-default-address', + 'Remove custom properties from the cart', + 'remove-cart-properties', ), + description: + 'Remove specific custom properties from the cart by providing an array of property keys. This example shows how to use `removeCartProperties()` to delete particular metadata fields while preserving other cart properties and data.', }, { codeblock: generateJsxCodeBlockForCartApi( - 'Add a selling plan to a line item in the cart', - 'add-line-item-selling-plan', + 'Remove the customer from the cart', + 'remove-customer', ), + description: + 'Disassociate the current customer from the cart while preserving cart contents. This example uses `removeCustomer()` to clear customer information, which removes customer-specific pricing and discounts but keeps all line items and other cart data intact.', }, { codeblock: generateJsxCodeBlockForCartApi( - 'Remove a selling plan from a line item in the cart', - 'remove-line-item-selling-plan', + 'Update the default address for the customer', + 'update-default-address', ), + description: + "Set a specific address as the customer's default address using its address ID. This example shows how to use `updateDefaultAddress()` to designate which address should be used by default for shipping or billing in future transactions.", }, ], }, diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/cart-line-item-api.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/cart-line-item-api.doc.ts index 925a86549f..5135aeaaf7 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/cart-line-item-api.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/cart-line-item-api.doc.ts @@ -9,42 +9,55 @@ const generateJsxCodeBlockForCartLineItemApi = ( const data: ReferenceEntityTemplateSchema = { name: 'Cart Line Item API', - description: ` -The Cart Line Item API provides an extension with data about the current Cart Line Item. - -#### Supporting targets -- ${TargetLink.PosCartLineItemDetailsActionMenuItemRender} -- ${TargetLink.PosCartLineItemDetailsActionRender} -`, + description: + 'The Cart Line Item API provides read-only access to a specific line item in the cart. Use this API to get line item details like product information, pricing, discounts, and custom properties. This allows you to build features that respond to the specific item a customer is viewing or interacting with.', isVisualComponent: false, type: 'APIs', definitions: [ { title: 'CartLineItemApi', - description: '', + description: + 'The `CartLineItemApi` object provides access to the current line item. Access this property through `api.cartLineItem` to interact with the current line item context.', type: 'CartLineItemApi', }, ], examples: { - description: 'Examples of using the Cart Line Item API.', + description: + 'Learn how to access line item information in cart line item action contexts.', examples: [ { codeblock: generateJsxCodeBlockForCartLineItemApi( - 'Retrieve the ID of the cart line item.', + 'Display the line item ID', 'id', ), + description: + 'Access the unique identifier of the current line item in a cart line item action context. This example shows how to use `shopify.cartLineItem.id` to retrieve the line item ID, which can be used for tracking, analytics, or performing operations on the specific item.', }, ], }, - category: 'APIs', - related: [ + category: 'Target APIs', + subCategory: 'Contextual APIs', + related: [], + subSections: [ { - name: ExtensionTargetType.PosCartLineItemDetailsActionMenuItemRender, - url: '/docs/api/pos-ui-extensions/targets/pos-cart-line-item-details-action-menu-item-render', + type: 'Generic', + anchorLink: 'best-practices', + title: 'Best practices', + sectionContent: + '- **Handle optional properties gracefully:** Check for `undefined` values in optional properties like `price`, `productId`, `title`, `sku`, `vendor`, and selling plan-related fields before using them in your extension logic.\n' + + '- **Use line item context effectively:** Use the line item data to create contextual experiences—for example, showing different interfaces for gift cards versus regular products, subscription items versus one-time purchases, or displaying vendor-specific information.\n' + + '- **Implement item-specific validation:** Use line item properties like `taxable`, `isGiftCard`, `requiresSellingPlan`, and `hasSellingPlanGroups` to implement appropriate validation and business logic for different item types.\n' + + '- **Handle selling plans appropriately:** When working with subscription products, check `requiresSellingPlan` and `sellingPlan` properties.\n' + + '- **Access related data efficiently:** Use `productId` and `variantId` to fetch additional product information when needed, but avoid unnecessary API calls by using the data already available in the line item.', }, { - name: ExtensionTargetType.PosCartLineItemDetailsActionRender, - url: '/docs/api/pos-ui-extensions/targets/pos-cart-line-item-details-action-render', + type: 'Generic', + anchorLink: 'limitations', + title: 'Limitations', + sectionContent: + '- The API provides read-only access to line item data—use the Cart API for modifying line item properties, discounts, selling plans, or other attributes.\n' + + '- Line item data reflects the current state and may not include real-time inventory, pricing, or selling plan updates until the cart is refreshed.\n' + + "- Selling plan information may be limited during refund or exchange operations where digest values aren't available.", }, ], }; 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 59b08e8c9f..9e6a4f693b 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 @@ -9,26 +9,52 @@ const generateJsxCodeBlockForConnectivityApi = ( const data: ReferenceEntityTemplateSchema = { name: 'Connectivity API', description: - 'The Connectivity API enables POS UI extensions to retrieve device connectivity information, such as whether the device has an internet connection.', + 'The Connectivity API provides access to device connectivity information, allowing you to monitor Internet connection status and respond to connectivity changes in real-time. The API enables both immediate connectivity checks and dynamic updates when network conditions change.', isVisualComponent: false, type: 'APIs', definitions: [ { title: 'ConnectivityApi', - description: '', + description: + 'The `ConnectivityApi` object provides access to current connectivity information and change notifications. Access these properties through `shopify.connectivity` to monitor network status.', type: 'ConnectivityApiContent', }, ], - category: 'APIs', + category: 'Target APIs', + subCategory: 'Platform APIs', related: [], + subSections: [ + { + type: 'Generic', + anchorLink: 'best-practices', + title: 'Best practices', + sectionContent: + '- **Handle connectivity changes gracefully:** Use the `subscribe` method to automatically adapt your extension behavior when connectivity changes.\n' + + '- **Design for connectivity awareness:** Design your extension to handle network interruptions, informing users when network-dependent features are unavailable and providing clear guidance on next steps.\n' + + '- **Provide clear connectivity feedback:** Display connectivity status to users when it affects functionality, helping them understand why certain features may be limited or unavailable.\n' + + '- **Queue operations during outages:** Implement queuing mechanisms for non-critical operations that can be deferred until connectivity is restored.', + }, + { + 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.\n" + + '- Connectivity status reflects Internet connectivity only and may not indicate the quality or speed of the connection, which could affect API performance.\n' + + "- The API monitors general Internet connectivity but doesn't provide specific information about Shopify service availability or API endpoint availability.", + }, + ], examples: { - description: 'Examples of using the Connectivity API', + description: + 'Learn how to monitor Internet connectivity status and respond to network changes.', examples: [ { codeblock: generateJsxCodeBlockForConnectivityApi( - 'Subscribe to connectivity changes.', + 'Monitor Internet connectivity status', 'subscribe', ), + description: + 'Subscribe to connectivity state changes to build network-aware extensions that respond to connectivity changes. This example shows how to use `shopify.connectivity.subscribe()` to receive real-time notifications when the device goes online or offline, allowing you to adapt your UI or disable features when Internet access is unavailable.', }, ], }, 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 c3038fc21e..3a70014ed0 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,52 @@ const generateJsxCodeBlockForCustomerApi = (title: string, fileName: string) => const data: ReferenceEntityTemplateSchema = { name: 'Customer API', - description: ` -The customer API provides an extension with data about the current customer. - -#### Supporting targets -- ${TargetLink.PosCustomerDetailsActionMenuItemRender} -- ${TargetLink.PosCustomerDetailsActionRender} -- ${TargetLink.PosCustomerDetailsBlockRender} -`, + description: + 'The Customer API provides read-only access to customer data. Use this API to get customer information and build personalized experiences based on the selected customer context. The API offers the customer identifier for linking to customer data and enabling customer-specific features.', isVisualComponent: false, type: 'APIs', definitions: [ { title: 'CustomerApi', - description: '', + description: + 'The `CustomerApi` object provides access to customer data. Access this property through `shopify.customer` to interact with the current customer context.', type: 'CustomerApiContent', }, ], examples: { - description: 'Examples of using the Customer API.', + description: + 'Learn how to access customer information in customer detail contexts.', examples: [ { codeblock: generateJsxCodeBlockForCustomerApi( - 'Retrieve the ID of the customer.', + 'Display the customer ID', 'id', ), + description: + 'Access the unique identifier of the current customer in a customer detail action context. This example shows how to use `shopify.customer.id` to retrieve the customer ID, which can be used for personalization, fetching additional customer data, or building customer-specific features.', }, ], }, - 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: + '- **Use customer ID for data lookups:** Use the customer ID to fetch additional customer information from external systems, CRM platforms, or Shopify APIs when building comprehensive customer experiences.\n' + + '- **Implement customer-specific features:** Use the customer context to enable personalized functionality like customer-specific pricing, loyalty program integration, or customized product recommendations.\n' + + '- **Validate customer access:** Verify that the customer ID is valid before performing customer-specific operations or external API calls.', }, { - 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.\n' + + '- 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 f95196f718..1aea405bb1 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,38 +7,68 @@ const generateJsxCodeBlockForDeviceApi = (title: string, fileName: string) => const data: ReferenceEntityTemplateSchema = { name: 'Device API', description: - 'The Device API allows the UI Extension to retrieve device information including the device name and ID.', + 'The Device API provides access to device information and capabilities, allowing you to retrieve device details, check device types, and adapt your extension behavior based on the POS hardware characteristics. The API enables device-aware functionality and responsive design based on device form factors.', isVisualComponent: false, type: 'APIs', definitions: [ { title: 'DeviceApi', - description: '', + description: + 'The `DeviceApi` object provides access to device information and capabilities. Access these properties and methods through `shopify.device` to retrieve device details and check device characteristics.', type: 'DeviceApiContent', }, ], - category: 'APIs', + category: 'Target APIs', + subCategory: 'Platform APIs', related: [], + subSections: [ + { + type: 'Generic', + anchorLink: 'best-practices', + title: 'Best practices', + sectionContent: + '- **Implement responsive design:** Use device type information to adapt your interface layouts, component sizes, and interaction patterns based on the device form factor and capabilities.\n' + + '- **Handle async device queries:** Handle the Promise-based device methods with async/await or `.then()` patterns, and implement appropriate error handling for device query failures.\n' + + '- **Cache device information appropriately:** Consider caching device information after the initial query to avoid repeated async calls, but ensure you handle cases where device characteristics might change during the session.\n' + + '- **Provide device-appropriate experiences:** Design different user experiences for tablets versus other devices, taking advantage of larger screens while ensuring functionality works across all supported device types.', + }, + { + 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.\n' + + "- The Device API provides read-only access to device information and can't be used to modify device settings or capabilities.\n" + + "- Device type detection is limited to basic form factor identification (tablet vs. non-tablet) and doesn't provide detailed hardware specifications or capabilities.", + }, + ], examples: { - description: 'Examples of using the Device API.', + description: + 'Learn how to access device information and adapt your extension based on device characteristics.', examples: [ { codeblock: generateJsxCodeBlockForDeviceApi( - 'Retrieve name of the device.', - 'name', + 'Check if the device is a tablet', + 'tablet', ), + description: + 'Determine whether the extension is running on a tablet form factor. This example shows how to use `shopify.device.isTablet()` to check the device type, allowing you to adapt your UI layout, component sizes, or features based on whether the device is a tablet or other form factor.', }, { codeblock: generateJsxCodeBlockForDeviceApi( - 'Retrieve the ID of the device.', + 'Display the device ID', 'device-id', ), + description: + 'Access the unique identifier of the POS device. This example demonstrates using `shopify.device.id` to retrieve the device ID, which can be used for device-specific configurations, tracking, or associating data with particular devices.', }, { codeblock: generateJsxCodeBlockForDeviceApi( - 'Check if device is a tablet.', - 'tablet', + 'Display the device name', + 'name', ), + description: + 'Access the name of the POS device running your extension. This example shows how to use `shopify.device.name` to retrieve the device name, which can be useful for debugging, analytics, or displaying device-specific information to users.', }, ], }, 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 2b1c5d33ee..3fed7a21fe 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 @@ -9,32 +9,29 @@ const generateJsxCodeBlockForDraftOrderApi = ( const data: ReferenceEntityTemplateSchema = { name: 'Draft Order API', - description: ` -The Draft Order API provides an extension with data about the current draft order. - - -#### Supporting targets -- ${TargetLink.PosDraftOrderDetailsActionMenuItemRender} -- ${TargetLink.PosDraftOrderDetailsActionRender} -- ${TargetLink.PosDraftOrderDetailsBlockRender} -`, + description: + 'The Draft Order API provides read-only access to draft order data. Use this API to get draft order information and build contextual experiences based on the selected draft order context. The API offers draft order details for implementing order-specific functionality and workflows.', isVisualComponent: false, type: 'APIs', definitions: [ { title: 'DraftOrderApi', - description: '', + description: + 'The `DraftOrderApi` object provides access to draft order data. Access this property through `api.draftOrder` to interact with the current draft order context.', type: 'DraftOrderApiContent', }, ], examples: { - description: 'Examples of using the Draft Order API.', + description: + 'Learn how to access draft order information in draft order detail contexts.', examples: [ { codeblock: generateJsxCodeBlockForDraftOrderApi( - 'Retrieve the ID of the draft order.', + 'Display the draft order ID', 'id', ), + description: + 'Access the unique identifier of the current draft order in a draft order detail action context. This example shows how to use `shopify.draftOrder.id` to retrieve the draft order ID, which can be used for tracking, fetching additional order data, or implementing draft order-specific workflows.', }, { codeblock: generateJsxCodeBlockForDraftOrderApi( @@ -44,8 +41,28 @@ The Draft Order API provides an extension with data about the current draft orde }, ], }, - category: 'APIs', + category: 'Target APIs', + subCategory: 'Contextual APIs', related: [], + subSections: [ + { + type: 'Generic', + anchorLink: 'best-practices', + title: 'Best practices', + sectionContent: + '- **Use draft order ID for data lookups:** Use the draft order ID to fetch additional draft order information from external systems, order management platforms, or Shopify APIs when building comprehensive draft order experiences.\n' + + '- **Implement draft order-specific features:** Use the draft order context to enable specialized functionality like draft order conversion, customer assignment, or order modification workflows.\n' + + '- **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.\n' + + '- 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 8347599a27..0913172e30 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,26 +7,52 @@ const generateJsxCodeBlockForLocaleApi = (title: string, fileName: string) => const data: ReferenceEntityTemplateSchema = { name: 'Locale API', description: - "The Locale API allows the extension to retrieve the merchant's locale.", + "The Locale API provides access to the merchant's current locale information in [IETF format](https://en.wikipedia.org/wiki/IETF_language_tag), allowing you to internationalize your extension content and respond to locale changes in real time. The API enables both immediate locale access and dynamic updates when merchants change their language settings.", isVisualComponent: false, type: 'APIs', definitions: [ { title: 'LocaleApi', - description: '', + description: + 'The `LocaleApi` object provides access to current locale information and change notifications. Access these properties through `shopify.locale` to retrieve and monitor locale data.', type: 'LocaleApiContent', }, ], - category: 'APIs', + category: 'Target APIs', + subCategory: 'Standard APIs', related: [], + subSections: [ + { + type: 'Generic', + anchorLink: 'best-practices', + title: 'Best practices', + sectionContent: + '- **Handle locale changes reactively:** Use the `subscribe` method to automatically update your extension content when merchants change their language settings.\n' + + "- **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.\n" + + '- **Cache localized content:** Consider caching translated content and locale-specific formatting to improve performance, but ensure you invalidate caches when locale changes occur through subscription updates.\n' + + '- **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.\n" + + "- Locale changes are detected through the subscription mechanism, but the API doesn't provide historical locale information or change timestamps.\n" + + '- The locale format follows IETF standards, but the specific locales available depend on POS system configuration and may vary between different Shopify POS installations.', + }, + ], examples: { - description: 'Examples of using the Locale API', + description: + 'Learn how to access locale information and respond to language changes for internationalization.', examples: [ { codeblock: generateJsxCodeBlockForLocaleApi( - 'Subscribe to locale changes.', + 'Monitor locale changes', 'subscribe', ), + description: + "Subscribe to locale changes to build internationalized extensions that automatically adapt to the merchant's language settings. This example shows how to use `shopify.locale.subscribe()` to receive real-time notifications when the merchant changes their language, allowing you to update your UI text, date formats, and number formats accordingly.", }, ], }, 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 b7330b65ba..f2f3335a53 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 @@ -9,53 +9,73 @@ const generateJsxCodeBlockForNavigationApi = ( const data: ReferenceEntityTemplateSchema = { name: 'Navigation API', - description: ` -The Navigation API enables POS UI extension to navigate between screens. - -#### Supporting targets -- ${TargetLink.PosHomeModalRender} -- ${TargetLink.PosPurchasePostActionRender} -- ${TargetLink.PosProductDetailsActionRender} -- ${TargetLink.PosOrderDetailsActionRender} -- ${TargetLink.PosDraftOrderDetailsActionRender} -- ${TargetLink.PosCustomerDetailsActionRender} -`, + description: + 'The Navigation API provides web-standard navigation functionality for POS UI extensions, allowing you to navigate between URLs, manage navigation history, and handle navigation events within modal interfaces. The API is available globally as the `navigation` object and follows web platform standards.', isVisualComponent: false, type: 'APIs', definitions: [ { title: 'NavigationApi', - description: '', + description: + 'The global `navigation` object provides web-standard navigation functionality. Access these properties and methods directly through the global `navigation` object to manage navigation within modal interfaces.', type: 'Navigation', }, { title: 'Window', - description: '', + description: + 'The global `window` object provides control over the extension screen lifecycle. Access these properties and methods directly through the global `window` object to manage the modal interface.', type: 'Window', }, ], - category: 'APIs', + category: 'Target APIs', + subCategory: 'Platform APIs', related: [], + subSections: [ + { + type: 'Generic', + anchorLink: 'best-practices', + title: 'Best practices', + sectionContent: + '- **Use URL-based navigation:** Implement URL-based navigation patterns that allow for deep-linking, bookmarking, and intuitive browser-like navigation within your modal workflows.\n' + + '- **Manage navigation state effectively:** Use the `state` parameter in navigation options to pass data between screens, maintaining workflow context and user progress across navigation changes.', + }, + { + 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.\n" + + "- Navigation state is limited to serializable data and can't contain functions, complex objects, or circular references.\n" + + '- The API follows web platform standards but operates within the POS modal context, so some web navigation behaviors may differ from standard browser navigation.', + }, + ], examples: { - description: 'Examples of using the Navigation API', + description: + 'Learn how to navigate between screens and manage navigation state within modal interfaces.', examples: [ { codeblock: generateJsxCodeBlockForNavigationApi( - 'Navigate between two screens', + 'Navigate between multiple screens', 'two-screen', ), + description: + 'Create multi-screen modal experiences by navigating between different URLs within your extension. This example demonstrates using `navigation.navigate()` to move between screens and handle back navigation, enabling complex workflows with multiple steps or views.', }, { codeblock: generateJsxCodeBlockForNavigationApi( - 'Navigate to a POS native screen with uri', + 'Navigate to a native POS screen', 'native-screen', ), + description: + 'Launch native POS screens using URI schemes to access built-in functionality. This example shows how to use `navigation.navigate()` with a `pos://` URI to open native POS screens like product details or customer profiles, allowing seamless integration between your extension and native POS features.', }, { codeblock: generateJsxCodeBlockForNavigationApi( - 'Navigate to a screen with state parameters', + 'Pass state parameters between screens', 'state-params', ), + description: + 'Share data between screens using navigation state parameters. This example demonstrates how to pass state objects when navigating, allowing you to transfer information between different screens in your modal workflow without relying on external storage or global variables.', }, ], }, 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 8c00a63e73..54ffddad40 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,36 +7,51 @@ const generateJsxCodeBlockForOrderApi = (title: string, fileName: string) => const data: ReferenceEntityTemplateSchema = { name: 'Order API', - description: ` -The Order API provides an extension with data about the current order. - -#### Supporting targets -- ${TargetLink.PosPurchasePostActionMenuItemRender} -- ${TargetLink.PosPurchasePostActionRender} -- ${TargetLink.PosPurchasePostBlockRender} -- ${TargetLink.PosOrderDetailsActionMenuItemRender} -- ${TargetLink.PosOrderDetailsActionRender} -- ${TargetLink.PosOrderDetailsBlockRender} -`, + description: + 'The Order API provides read-only access to order data. Use this API to get order information and build contextual experiences based on the selected order context. The API offers order details for implementing order-specific functionality and workflows.', isVisualComponent: false, type: 'APIs', definitions: [ { title: 'OrderApi', - description: '', + description: + 'The `OrderApi` object provides access to order data. Access this property through `shopify.order` to interact with the current order context.', type: 'OrderApiContent', }, ], - category: 'APIs', + category: 'Target APIs', + subCategory: 'Contextual APIs', related: [], + subSections: [ + { + type: 'Generic', + anchorLink: 'best-practices', + title: 'Best practices', + sectionContent: + '- **Use order ID for data lookups:** Use the order ID to fetch additional order information from external systems, order management platforms, or Shopify APIs when building comprehensive order experiences.\n' + + '- **Implement order-specific features:** Use the order context to enable specialized functionality like order fulfillment, customer communication, or order modification workflows.\n' + + '- **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.\n' + + '- Order data reflects the current POS session and may not include real-time updates from other channels until the session is refreshed.', + }, + ], examples: { - description: 'Examples of using the Order API.', + description: + 'Learn how to access order information in order detail contexts.', examples: [ { codeblock: generateJsxCodeBlockForOrderApi( - 'Retrieve the ID of the order.', + 'Display the order ID', 'id', ), + description: + 'Access the unique identifier of the current order in an order detail action context. This example shows how to use `shopify.order.id` to retrieve the order ID, which can be used for fetching additional order data, tracking, or implementing order-specific functionality and post-purchase workflows.', }, { codeblock: generateJsxCodeBlockForOrderApi( diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/pinpad-api.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/pinpad-api.doc.ts index cd219b91b7..27d3f6268d 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/pinpad-api.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/pinpad-api.doc.ts @@ -7,26 +7,52 @@ const generateJsxCodeBlockForToastApi = (title: string, fileName: string) => const data: ReferenceEntityTemplateSchema = { name: 'PinPad API', description: - 'The PinPad API allows the display of a PinPad component for PIN validation.', + 'The PinPad API provides secure PIN entry functionality for POS UI extensions, allowing you to display modal PIN pad interfaces for secure PIN collection, validation, and processing with customizable options and callback handling. The API enables secure authentication workflows within your extensions.', isVisualComponent: false, type: 'APIs', definitions: [ { title: 'PinPadApi', - description: '', + description: + 'The `PinPadApi` object provides methods for displaying secure PIN entry interfaces. Access these methods through `shopify.pinPad` to show PIN pad modals and handle PIN validation.', type: 'PinPadApiContent', }, ], - category: 'APIs', + category: 'Target APIs', + subCategory: 'Platform APIs', related: [], + subSections: [ + { + type: 'Generic', + anchorLink: 'best-practices', + title: 'Best practices', + sectionContent: + '- **Implement secure PIN validation:** Validate PINs securely on your backend service rather than in client-side code, using the `onSubmit` callback to communicate with your secure validation endpoint.\n' + + '- **Provide clear user feedback:** Use appropriate labels, titles, and error messages to guide users through the PIN entry process.\n' + + '- **Handle PIN entry appropriately:** Implement proper error handling for PIN validation failures, provide retry mechanisms, and ensure sensitive PIN data is handled securely throughout the process.\n' + + '- **Configure appropriate PIN constraints:** Set reasonable PIN length requirements and masking options based on your security requirements and user experience considerations.', + }, + { + type: 'Generic', + anchorLink: 'limitations', + title: 'Limitations', + sectionContent: + '- PIN validation must be handled through the `onSubmit` callback and should be performed securely on your backend service rather than in client-side extension code.\n' + + '- The PinPad API displays a modal interface that takes over the entire screen until PIN entry is complete or the modal is dismissed.\n' + + '- PIN data is provided as an array of numbers and must be handled securely, following appropriate data protection and privacy practices.', + }, + ], examples: { - description: 'Examples of using the PinPad API', + description: + 'Learn how to display secure PIN entry interfaces and handle PIN validation.', examples: [ { codeblock: generateJsxCodeBlockForToastApi( - 'Display a PinPad and validate the PIN', + 'Display a PIN pad and validate user input', 'validation', ), + description: + 'Present a secure PIN pad interface to collect and validate user PINs for authentication or verification. This example shows how to use `shopify.pinPad.show()` to display a PIN entry modal with customizable options, handle the entered PIN securely, and process the result for secure authentication workflows.', }, { codeblock: generateJsxCodeBlockForToastApi( 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 33af445a72..0062abef9f 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 @@ -6,59 +6,74 @@ const generateJsxCodeBlockForPrintApi = (title: string, fileName: string) => const data: ReferenceEntityTemplateSchema = { name: 'Print API', - description: `The Print API enables document printing functionality in your point of sale extension. Use this API to trigger the native print dialog for your documents. - -The \`print()\` method accepts 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 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)`, + 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\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.', 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 `shopify.print` to initiate print operations with various document types.', type: 'PrintApiContent', }, ], - category: 'APIs', - related: [ + category: 'Target APIs', + subCategory: 'Platform APIs', + related: [], + subSections: [ { - name: 'PrintPreview Component', - subtitle: 'Preview documents before printing', - url: '/api/pos-ui-extensions/components/printpreview', + type: 'Generic', + anchorLink: 'best-practices', + title: 'Best practices', + sectionContent: + '- **Use appropriate document formats:** Choose HTML for rich formatting and responsive design, text for simple content, images for graphics, and PDFs for complex documents while considering platform limitations.\n' + + '- **Handle printing errors gracefully:** Implement proper error handling for print operations, including network failures, unsupported document types, or printer connectivity issues.\n' + + '- **Optimize documents for printing:** Design your printable documents with appropriate sizing, margins, and formatting that work well with printers and standard paper sizes.\n' + + '- **Provide user feedback:** Give users clear feedback about print operations, including loading states, success confirmations, and error messages when printing fails.', }, { - name: 'Build a Print Extension', - subtitle: 'Learn how to implement printing', - url: '/docs/apps/build/pos/build-print-extension?extension=preact', + 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.\n' + + '- Print operations depend on device printer connectivity and configuration, which may not be available in all POS setups.\n' + + '- Document formatting and appearance may vary depending on the printer type, paper size, and device capabilities.', }, ], examples: { - description: 'Examples of using the Print API', + description: + 'Learn how to trigger document printing for receipts, labels, and custom documents.', examples: [ { codeblock: generateJsxCodeBlockForPrintApi( - 'Print directly from the tile', + 'Print a document directly from a tile', 'print', ), + description: + 'Trigger the native print dialog from a smart grid tile action. This example shows how to use `shopify.print()` to print a document specified by a relative path, allowing quick printing of receipts, labels, or reports directly from the POS home screen.', }, { codeblock: generateJsxCodeBlockForPrintApi( - 'Print with relative path', - 'print-relative', + 'Print from a remote URL', + 'print-full-url', ), + description: + 'Print documents hosted on external servers using full URLs. This example shows how to use `shopify.print()` with a complete URL to print remotely hosted documents, enabling dynamic content generation or printing from external services.', }, { codeblock: generateJsxCodeBlockForPrintApi( - 'Print with full URL', - 'print-full-url', + 'Print using a relative file path', + 'print-relative', ), + description: + 'Print documents using relative paths within your extension bundle. This example demonstrates using `shopify.print()` with a relative path to reference HTML, text, image, or PDF files included in your extension, making it easy to print pre-defined templates or documents.', }, ], }, 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 2d2dc54e1a..324774e2f3 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,31 +7,29 @@ const generateJsxCodeBlockForProductApi = (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} -- ${TargetLink.PosProductDetailsBlockRender} -`, + 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 `shopify.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 in product detail contexts.', examples: [ { codeblock: generateJsxCodeBlockForProductApi( - 'Retrieve the ID of the product.', + 'Display the product ID', 'id', ), + description: + 'Access the unique identifier of the current product in a product detail action context. This example shows how to use `shopify.product.id` to retrieve the product ID, which can be used for fetching additional product data, analytics, or implementing product-specific features and workflows.', }, { codeblock: generateJsxCodeBlockForProductApi( @@ -41,15 +39,26 @@ The Product API provides an extension with data about the current Product. }, ], }, - 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: + '- **Use product ID for data lookups:** Use the product ID to fetch additional product information from external systems, inventory management platforms, or Shopify APIs when building comprehensive product experiences.\n' + + '- **Implement variant-specific features:** Use the variant ID to enable specialized functionality like variant-specific pricing, inventory checks, or cart operations.\n' + + '- **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.\n' + + '- 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 dd44381043..82a9bb28f1 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,56 +9,92 @@ const generateJsxCodeBlockForProductSearchApi = ( 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 retrieving product information. Access these methods through `shopify.productSearch` to search products and fetch detailed product data.', type: 'ProductSearchApiContent', }, ], - category: 'APIs', + category: 'Target APIs', + subCategory: 'Standard APIs', related: [], + subSections: [ + { + type: 'Generic', + anchorLink: 'best-practices', + title: 'Best practices', + sectionContent: + '- **Implement efficient pagination:** Use appropriate page sizes and cursor-based pagination to balance performance with user experience, especially for large product catalogs.\n' + + '- **Handle search results gracefully:** Check for undefined results and empty result sets.\n' + + '- **Optimize search performance:** Consider caching frequently accessed product data and implementing debounced search to reduce API calls while users are typing search queries.\n' + + '- **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.\n" + + '- Bulk operations (`fetchProductsWithIds` and `fetchProductVariantsWithIds`) are limited to 50 items maximum, with additional IDs automatically removed from requests.\n' + + '- Search functionality depends on local product data synchronization and may not reflect real-time inventory or pricing changes until the next sync.', + }, + ], examples: { - description: 'Examples of using the Cart API', + description: + 'Learn how to search for products, fetch product details, and retrieve variants.', examples: [ { codeblock: generateJsxCodeBlockForProductSearchApi( - 'Search for products with a search bar', - 'search-products', + 'Fetch multiple products by IDs', + 'fetch-products-with-ids', ), + description: + 'Retrieve detailed information for multiple products in a single request using their IDs. This example shows how to use `shopify.productSearch.fetchByIds()` to efficiently fetch data for multiple products at once, improving performance when displaying product lists or related items.', }, { codeblock: generateJsxCodeBlockForProductSearchApi( - 'Fetch a specific product with a product ID', - 'fetch-product-with-id', + 'Fetch multiple variants by IDs', + 'fetch-product-variants-with-ids', ), + description: + 'Retrieve detailed information for multiple product variants in a single request using their IDs. This example shows how to use `shopify.productSearch.fetchVariantsByIds()` to efficiently fetch data for multiple variants at once, useful for displaying variant lists or comparisons.', }, { codeblock: generateJsxCodeBlockForProductSearchApi( - 'Fetch multiple products by specifying product IDs', - 'fetch-products-with-ids', + 'Fetch paginated variants for a product', + 'fetch-paginated-product-variants-with-product-id', ), + description: + 'Retrieve product variants with pagination support for products with many variants. This example demonstrates using `shopify.productSearch.fetchVariantsByProductId()` with pagination parameters to load variants page by page, improving performance and user experience for products with large variant catalogs.', }, { codeblock: generateJsxCodeBlockForProductSearchApi( - 'Fetch a specific product variant with a variant ID', - 'fetch-product-variant-with-id', + 'Fetch a single product by ID', + 'fetch-product-with-id', ), + description: + 'Retrieve detailed information for a specific product using its ID. This example demonstrates using `shopify.productSearch.fetchById()` to get complete product data including variants, pricing, and inventory information for a single product.', }, { codeblock: generateJsxCodeBlockForProductSearchApi( - 'Fetch multiple product variants by specifying variant IDs', - 'fetch-product-variants-with-ids', + 'Fetch a single variant by ID', + 'fetch-product-variant-with-id', ), + description: + 'Retrieve detailed information for a specific product variant using its ID. This example demonstrates using `shopify.productSearch.fetchVariantById()` to get variant-specific data including pricing, inventory, and options for a particular variant.', }, { codeblock: generateJsxCodeBlockForProductSearchApi( - 'Fetch a page of product variants with a specific product ID', - 'fetch-paginated-product-variants-with-product-id', + 'Search for products using a search bar', + 'search-products', ), + description: + 'Search for products using text queries with real-time results. This example shows how to use `shopify.productSearch.search()` to perform text-based product searches with pagination support, allowing users to find products by name, SKU, or other searchable attributes.', }, ], }, 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 b9d9017b60..69ee2dae34 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,36 +7,53 @@ 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.PosCustomerDetailsActionRender} -`, + 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 in real-time. 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 `shopify.scanner` to monitor scan events and available scanner sources.', type: 'ScannerApiContent', }, ], - category: 'APIs', + category: 'Target APIs', + subCategory: 'Platform APIs', related: [], + subSections: [ + { + type: 'Generic', + anchorLink: 'best-practices', + title: 'Best practices', + sectionContent: + '- **Handle scan events reactively:** Use the `subscribe` methods to automatically process scan events as they occur.\n' + + '- **Validate scanned data appropriately:** Validate scanned data before processing, implementing proper error handling for invalid codes, unsupported formats, or scanning errors.\n' + + '- **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.\n' + + '- **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.\n" + + '- Scanning availability depends on device hardware capabilities and may vary between different POS devices and configurations.\n' + + '- Scan data processing is reactive and requires proper subscription management to avoid memory leaks or unexpected behavior when components unmount.', + }, + ], examples: { - description: 'Examples of receiving updates from the Scanner API', + description: + 'Learn how to handle barcode and QR code scans and access scanner information.', examples: [ { codeblock: generateCodeBlockForScannerApi( - 'Render conditionally based on available scanner sources', + 'Respond to scan events based on scanner source', 'conditional-scanner-example', ), + description: + 'Subscribe to scan events and adapt behavior based on the scanner source. This example shows how to use `shopify.scanner.subscribe()` to receive scan events and check `shopify.scanner.source` to determine which scanner type was used (camera, external scanner, or embedded hardware), allowing you to customize handling based on the scanning method.', }, { codeblock: generateCodeBlockForScannerApi( 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 cabd845394..eb11587435 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,26 +7,52 @@ const generateJsxCodeBlockForSessionApi = (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 `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).', type: 'SessionApiContent', }, ], - category: 'APIs', + category: 'Target APIs', + subCategory: 'Standard APIs', related: [], + subSections: [ + { + type: 'Generic', + anchorLink: 'best-practices', + title: 'Best practices', + sectionContent: + '- **Handle authentication properly:** Check for undefined session tokens and implement proper fallback behavior when authentication fails or permissions are insufficient.\n' + + '- **Use appropriate identifiers:** Distinguish between `userId` (authenticated account) and `staffMemberId` (pinned staff member) to implement correct permissions and personalization logic.\n' + + '- **Implement location-aware features:** Use `locationId` and `currency` information.\n' + + '- **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.\n" + + "- 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.\n" + + "- 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.", + }, + ], examples: { - description: 'Examples of using the Session API', + description: + 'Learn how to access session information and generate authentication tokens for secure API calls.', examples: [ { codeblock: generateJsxCodeBlockForSessionApi( - 'Retrieve a session token for backend communication', + 'Access session data and generate authentication tokens', 'token', ), + description: + 'Retrieve current session information and generate secure authentication tokens for backend API calls. This example shows how to access shop details, user information, and location data through `shopify.session`, and use `shopify.session.getSessionToken()` to generate tokens for authenticated requests to your backend services.', }, { codeblock: generateJsxCodeBlockForSessionApi( diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/storage-api.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/storage-api.doc.ts index f92731daca..02105fe74b 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/storage-api.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/storage-api.doc.ts @@ -6,54 +6,88 @@ const generateJsxCodeBlockForStorageApi = (title: string, fileName: string) => const data: ReferenceEntityTemplateSchema = { name: 'Storage API', - description: `The Storage API allows fetching, setting, updating, and clearing an extension's data from the POS local storage. - - An extension can store up to 100 entries. - - The maximum size for a key is ~1 KB, and for a value is ~1 MB. - - If a target (such as \`pos.home.tile.render\`) is disabled or removed, the extension data remains. - - All stored extension data that has not been updated for a month is cleared automatically after that period.`, + description: + 'The Storage API provides persistent local storage for POS UI extensions, allowing you to store, retrieve, and manage extension data that persists across user sessions, device restarts, and extension target state changes. Data is stored locally on the POS device in an isolated namespace specific to your extension.' + + '\n\nThe API supports key-value storage with automatic JSON serialization, type safety through TypeScript interfaces, and built-in error handling for storage constraint violations.', isVisualComponent: false, type: 'APIs', - category: 'APIs', + category: 'Target APIs', + subCategory: 'Standard APIs', related: [], + subSections: [ + { + type: 'Generic', + anchorLink: 'best-practices', + title: 'Best practices', + sectionContent: + '- **Design consistent key naming patterns:** Use hierarchical key names like `settings.user.theme` or `cache.products.$' + + '{id}` to organize related data and make storage contents easier to understand and maintain.\n' + + '- **Validate retrieved data:** Check data structure and types after calling `get()` since stored data may be outdated or corrupted. Provide sensible defaults and handle missing properties.\n' + + '- **Plan for data evolution:** Design your stored data structures to handle future changes. Include version fields in complex objects and implement migration logic to handle schema updates between extension versions.\n' + + '- **Keep sensitive data out of local storage:** Never store passwords, API keys, or other sensitive information. Use the Session API for secure backend communication and limit stored data to user preferences and non-sensitive workflow state.', + }, + { + type: 'Generic', + anchorLink: 'limitations', + title: 'Limitations', + sectionContent: + '- POS UI extensions can store up to a maximum of 100 entries.\n' + + '- The maximum key size is ~1 KB and the maximum value size is ~1 MB.\n' + + '- Data persists even when extension targets are disabled or removed.\n' + + '- Stored extension data is automatically cleared after 30 days of inactivity.', + }, + ], definitions: [ { title: 'StorageApi', - description: '', + description: + 'The `StorageApi` object provides access to persistent local storage methods for your POS UI extension. Access these methods through `shopify.storage` to store, retrieve, and manage data that persists across sessions.', type: 'Storage', }, ], examples: { - description: 'Examples of using the Storage API', + description: + 'Learn how to store and retrieve persistent data that persists across sessions.', examples: [ { codeblock: generateJsxCodeBlockForStorageApi( - 'Getting a single value from storage', - 'get', + 'Clear all stored values', + 'clear', ), + description: + 'Remove all stored data for your extension from persistent storage. This example demonstrates using `shopify.storage.clear()` to delete all key-value pairs stored by your extension, useful for reset functionality or clearing user preferences.', }, { codeblock: generateJsxCodeBlockForStorageApi( - 'Setting a single value in storage', - 'set', + 'Remove a value from storage', + 'delete', ), + description: + 'Delete a specific value from storage using its key. This example shows how to use `shopify.storage.delete()` to remove a stored item, permanently clearing the data associated with that key while leaving other stored values intact.', }, { codeblock: generateJsxCodeBlockForStorageApi( - 'Deleting a single value from storage', - 'delete', + 'Retrieve all stored entries', + 'entries', ), + description: + 'Fetch all key-value pairs stored by your extension. This example shows how to use `shopify.storage.entries()` to retrieve an array of all stored items, useful for displaying saved data, performing bulk operations, or exporting stored information.', }, { codeblock: generateJsxCodeBlockForStorageApi( - 'Clear all entries for an extension from storage', - 'clear', + 'Retrieve a value from storage', + 'get', ), + description: + 'Read a stored value using its key from persistent storage. This example shows how to use `shopify.storage.get()` to retrieve a previously saved value, which returns the stored data with automatic JSON deserialization or undefined if the key does not exist.', }, { codeblock: generateJsxCodeBlockForStorageApi( - 'Retrieve all entries for an extension from storage', - 'entries', + 'Save a value to storage', + 'set', ), + description: + 'Store a value in persistent storage using a key-value pair. This example demonstrates using `shopify.storage.set()` to save data that will persist across user sessions, device restarts, and extension reloads, with automatic JSON serialization of the value.', }, ], }, 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 403317fae7..3b088b7dff 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,26 +6,53 @@ const generateJsxCodeBlockForToastApi = (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 `shopify.toast` to show user feedback and status updates.', type: 'ToastApiContent', }, ], - category: 'APIs', + category: 'Target APIs', + subCategory: 'Standard APIs', related: [], + subSections: [ + { + type: 'Generic', + anchorLink: 'best-practices', + title: 'Best practices', + sectionContent: + '- **Write clear, concise messages:** Keep toast content brief and actionable since users have limited time to read the message before it disappears automatically.\n' + + '- **Use appropriate timing:** Choose duration values that give users enough time to read the message without keeping notifications visible longer than necessary.\n' + + '- **Provide meaningful feedback:** Use toast messages to confirm successful actions, explain errors clearly, or communicate important status changes that users need to know about.\n' + + '- **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.\n" + + '- Multiple toast messages may overlap or interfere with each other if shown in rapid succession. Consider queuing or spacing out notifications appropriately.\n' + + "- Toast content is limited to plain text and can't include rich formatting, links, or interactive elements.", + }, + ], examples: { - description: 'Examples of using the Toast API', + description: + 'Learn how to display temporary notification messages for user feedback.', examples: [ { codeblock: generateJsxCodeBlockForToastApi( - 'Display a Toast component from the tile', + 'Display a toast notification from a tile', 'show', ), + description: + "Show a temporary notification message to provide user feedback. This example demonstrates using `shopify.toast.show()` to display a brief, non-intrusive message that automatically disappears after a specified duration, useful for confirmations, status updates, or success messages that don't require user interaction.", }, { codeblock: generateJsxCodeBlockForToastApi( diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.cart-line-item-details-action-menu-item-render.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.cart-line-item-details-action-menu-item-render.doc.ts index 0f4c9f46df..4e167cd41f 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.cart-line-item-details-action-menu-item-render.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.cart-line-item-details-action-menu-item-render.doc.ts @@ -5,23 +5,21 @@ import {ExtensionTargetType} from '../types/ExtensionTargetType'; const data: ReferenceEntityTemplateSchema = { name: ExtensionTargetType.PosCartLineItemDetailsActionMenuItemRender, description: - 'A static extension target that renders as a menu item on the cart line item details screen', + 'Renders a single interactive button component as a menu item in the cart line item action menu. Use this target for item-specific operations like applying discounts, adding custom properties, or launching verification workflows for individual cart items.' + + '\n\nExtensions at this target can access detailed line item information including title, quantity, price, discounts, properties, and product metadata through the Cart Line Item API. Menu items typically invoke `shopify.action.presentModal()` to launch the companion modal for complete workflows.', defaultExample: { codeblock: generateJsxCodeBlock( - 'Action Menu Item', + 'Create a cart line item action menu item', 'targets', 'pos-cart-line-item-details-action-menu-item-render', ), + description: + 'Add an interactive menu item to the cart line item action menu for item-specific operations. This example shows how to create a menu item that accesses line item data and launches modal workflows for tasks like applying discounts, adding custom properties, or verification workflows.', }, category: 'Targets', - subCategory: 'Action', + subCategory: 'Cart line item', isVisualComponent: false, - related: [ - { - name: ExtensionTargetType.PosCartLineItemDetailsActionRender, - url: 'pos-cart-line-item-details-action-render', - }, - ], + related: [], type: 'Target', }; diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.cart-line-item-details-action-render.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.cart-line-item-details-action-render.doc.ts index 8001b5fdd5..994aa2ba7c 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.cart-line-item-details-action-render.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.cart-line-item-details-action-render.doc.ts @@ -5,23 +5,21 @@ import {ExtensionTargetType} from '../types/ExtensionTargetType'; const data: ReferenceEntityTemplateSchema = { name: ExtensionTargetType.PosCartLineItemDetailsActionRender, description: - 'A full-screen extension target that renders when a `pos.cart.line-item-details.action.menu-item.render` target calls for it', + 'Renders a full-screen modal interface launched from cart line item menu items. Use this target for complex line item 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 detailed line item data through the Cart Line Item API and support workflows with multiple screens, navigation, and interactive components.', defaultExample: { codeblock: generateJsxCodeBlock( - 'Action Render', + 'Create a cart line item action modal', 'targets', 'pos-cart-line-item-details-action-render', ), + description: + 'Build a full-screen modal workflow launched from a cart line item action menu item. This example demonstrates creating line item-specific experiences with multi-step processes, forms, and detailed line item data access for operations like customization or verification.', }, category: 'Targets', - subCategory: 'Action', + subCategory: 'Cart line item', isVisualComponent: false, - related: [ - { - name: ExtensionTargetType.PosCartLineItemDetailsActionMenuItemRender, - url: 'pos-cart-line-item-details-action-menu-item-render', - }, - ], + related: [], type: 'Target', }; 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 78a47163ff..5522f6a99f 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 `shopify.action.presentModal()` to launch the companion modal for complete customer workflows.', defaultExample: { codeblock: generateJsxCodeBlock( - '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 loyalty rewards, updating profiles, or managing customer preferences.', }, category: 'Targets', - subCategory: 'Action', + subCategory: 'Customer details', isVisualComponent: false, - related: [ - { - name: ExtensionTargetType.PosCustomerDetailsActionRender, - url: 'pos-customer-details-action-render', - }, - { - name: ExtensionTargetType.PosCustomerDetailsBlockRender, - url: '../block/pos-customer-details-block-render', - }, - { - name: 'Customer API', - url: '../../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 d7b6be8c74..8dc7716f14 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: generateJsxCodeBlock( - 'Action', + 'Create a customer details action modal', 'targets', 'customer-details-action', ), + description: + 'Build a full-screen modal workflow launched from a customer details action menu item. This example demonstrates creating customer-specific experiences with multi-step processes, forms, and customer data access for operations like loyalty management or profile updates.', }, category: 'Targets', - subCategory: 'Action', + subCategory: 'Customer details', isVisualComponent: false, - related: [ - { - name: ExtensionTargetType.PosCustomerDetailsActionMenuItemRender, - url: 'pos-customer-details-action-menu-item-render', - }, - { - name: ExtensionTargetType.PosCustomerDetailsBlockRender, - url: '../block/pos-customer-details-block-render', - }, - { - name: 'Customer API', - url: '../../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 35ba9d6ab1..fff1cd9d94 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 `shopify.action.presentModal()` for more complex customer operations.', defaultExample: { codeblock: generateJsxCodeBlock( - 'Block', + 'Create a customer details information block', 'targets', 'pos-customer-details-block-render', ), + description: + 'Add a custom information section to the customer details screen for displaying supplementary customer data. This example shows how to create a block that shows loyalty status, points balance, or personalized information alongside standard customer details.', }, category: 'Targets', - subCategory: 'Block', + subCategory: 'Customer details', isVisualComponent: false, - related: [ - { - name: ExtensionTargetType.PosCustomerDetailsActionMenuItemRender, - url: '../action/pos-customer-details-action-menu-item-render', - }, - { - name: ExtensionTargetType.PosCustomerDetailsActionRender, - url: '../action/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 c144799d58..aee8eba95b 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 `shopify.action.presentModal()` to launch the companion modal for complete draft order workflows.', defaultExample: { codeblock: generateJsxCodeBlock( - '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 data and launches modal workflows for tasks like sending invoices, updating payment status, or custom workflow processes.', }, category: 'Targets', - subCategory: 'Action', + subCategory: 'Draft order details', isVisualComponent: false, - related: [ - { - name: ExtensionTargetType.PosDraftOrderDetailsActionRender, - url: 'pos-draft-order-details-action-render', - }, - { - name: ExtensionTargetType.PosDraftOrderDetailsBlockRender, - url: '../block/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 5dc2c65133..e6012ac735 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.menu-item.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: generateJsxCodeBlock( - 'Draft order details action', + 'Create a draft order details action modal', 'targets', 'pos-draft-order-details-action', ), + description: + 'Build a full-screen modal workflow launched from a draft order details action menu item. This example demonstrates creating draft order-specific experiences with multi-step processes, forms, and draft order data access for operations like payment processing or order modifications.', }, category: 'Targets', - subCategory: 'Action', + subCategory: 'Draft order details', isVisualComponent: false, - related: [ - { - name: ExtensionTargetType.PosDraftOrderDetailsActionMenuItemRender, - url: 'pos-draft-order-details-action-menu-item-render', - }, - { - name: ExtensionTargetType.PosDraftOrderDetailsBlockRender, - url: '../block/pos-draft-order-details-block-render', - }, - { - name: 'Draft order details API', - url: '../../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 e4a83930af..04ac0e233c 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 `shopify.action.presentModal()` for more complex draft order operations.', defaultExample: { codeblock: generateJsxCodeBlock( - 'Block', + 'Create a draft order details information block', 'targets', 'pos-draft-order-details-block-render', ), + description: + 'Add a custom information section to the draft order details screen for displaying supplementary draft order data. This example shows how to create a block that provides additional draft order information, payment status, or custom order notes alongside standard draft order details.', }, category: 'Targets', - subCategory: 'Block', + subCategory: 'Draft order details', isVisualComponent: false, - related: [ - { - name: ExtensionTargetType.PosDraftOrderDetailsActionMenuItemRender, - url: '../action/pos-draft-order-details-action-menu-item-render', - }, - { - name: ExtensionTargetType.PosDraftOrderDetailsActionRender, - url: '../action/pos-draft-order-details-action-render', - }, - ], + related: [], type: 'Target', }; diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.exchange.post.action.menu-item.render.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.exchange.post.action.menu-item.render.doc.ts index 1798cbfaab..81c00032db 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.exchange.post.action.menu-item.render.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.exchange.post.action.menu-item.render.doc.ts @@ -4,33 +4,22 @@ import {ExtensionTargetType} from '../types/ExtensionTargetType'; const data: ReferenceEntityTemplateSchema = { name: ExtensionTargetType.PosExchangePostActionMenuItemRender, - description: `A static extension target that renders as a menu item on the post-exchange screen - > 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 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.' + + '\n\nExtensions at this target can access the order identifier through the Order API to perform exchange-specific operations. Menu items typically invoke `shopify.action.presentModal()` to launch the companion modal for complete post-exchange workflows.', defaultExample: { codeblock: generateJsxCodeBlock( - 'Exchange Post Action Menu Item', + 'Create a post-exchange action menu item', 'targets', 'pos-exchange-post-action-menu-item-render', ), + description: + 'Add an interactive menu item to the post-exchange action menu for operations after completing an exchange. This example shows how to create a menu item that accesses order data and launches modal workflows for tasks like generating exchange receipts, processing restocking, or collecting feedback.', }, category: 'Targets', - subCategory: 'Action', + subCategory: 'Post-exchange', isVisualComponent: false, - related: [ - { - name: ExtensionTargetType.PosExchangePostActionRender, - subtitle: 'Target', - type: 'blocks', - url: 'pos-exchange-post-action-render', - }, - { - name: ExtensionTargetType.PosExchangePostBlockRender, - subtitle: 'Target', - type: 'blocks', - url: '../block/pos-exchange-post-block-render', - }, - ], + related: [], type: 'Target', }; diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.exchange.post.action.render.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.exchange.post.action.render.doc.ts index 3d6879706b..90ab6592ac 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.exchange.post.action.render.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.exchange.post.action.render.doc.ts @@ -4,34 +4,22 @@ import {ExtensionTargetType} from '../types/ExtensionTargetType'; const data: ReferenceEntityTemplateSchema = { name: ExtensionTargetType.PosExchangePostActionRender, - description: `A full-screen extension target that renders when a \`pos.exchange.post.action.menu-item.render\` target calls for it - - > 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 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.' + + '\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: generateJsxCodeBlock( - 'Exchange Post Action', + 'Create a post-exchange action modal', 'targets', 'pos-exchange-post-action-render', ), + description: + 'Build a full-screen modal workflow launched from a post-exchange action menu item. This example demonstrates creating complex post-exchange experiences with multi-step processes, forms, and order data access for operations like inventory management or exchange analytics.', }, category: 'Targets', - subCategory: 'Action', + subCategory: 'Post-exchange', isVisualComponent: false, - related: [ - { - name: ExtensionTargetType.PosExchangePostActionMenuItemRender, - subtitle: 'Target', - type: 'blocks', - url: 'pos-exchange-post-action-menu-item-render', - }, - { - name: ExtensionTargetType.PosExchangePostBlockRender, - subtitle: 'Target', - type: 'blocks', - url: '../block/pos-exchange-post-block-render', - }, - ], + related: [], type: 'Target', }; diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.exchange.post.block.render.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.exchange.post.block.render.doc.ts index 65c932bfb3..8c74c3bc95 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.exchange.post.block.render.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.exchange.post.block.render.doc.ts @@ -4,33 +4,22 @@ import {ExtensionTargetType} from '../types/ExtensionTargetType'; const data: ReferenceEntityTemplateSchema = { name: ExtensionTargetType.PosExchangePostBlockRender, - description: `Renders a custom section within the native post exchange screen - > 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 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.' + + '\n\nExtensions at this target appear as persistent blocks within the post-exchange interface and support interactive elements that can launch modal workflows using `shopify.action.presentModal()` for more complex post-exchange operations.', defaultExample: { codeblock: generateJsxCodeBlock( - 'Exchange Post Block', + 'Create a post-exchange information block', 'targets', 'pos-exchange-post-block-render', ), + description: + 'Add a custom information section to the post-exchange screen for displaying exchange details or status. This example shows how to create a block that provides supplementary information after completing an exchange, with interactive elements that can launch modal workflows.', }, category: 'Targets', - subCategory: 'Block', + subCategory: 'Post-exchange', isVisualComponent: false, - related: [ - { - name: ExtensionTargetType.PosExchangePostActionMenuItemRender, - subtitle: 'Target', - type: 'blocks', - url: '../action/pos-exchange-post-action-menu-item-render', - }, - { - name: ExtensionTargetType.PosExchangePostActionRender, - subtitle: 'Target', - type: 'blocks', - url: '../action/pos-exchange-post-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 c81b705227..ba99ab0b94 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,23 +4,21 @@ import {generateJsxCodeBlock} 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: generateJsxCodeBlock( - 'Modal', + 'Create a full-screen modal for a smart grid tile', 'targets', 'pos-home-modal-render', ), + description: + 'Build a complete workflow experience launched from a smart grid tile. This example demonstrates creating a full-screen modal with navigation, multiple screens, and interactive components for sophisticated workflows that require more space than the tile interface provides.', }, category: 'Targets', - subCategory: 'Tile', + subCategory: 'Smart grid', isVisualComponent: false, - related: [ - { - name: 'pos.home.tile.render', - url: '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 6001e652b3..d7720abcb7 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 {generateJsxCodeBlock} 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 `shopify.action.presentModal()` to launch the companion modal for complete workflows.', defaultExample: { - codeblock: generateJsxCodeBlock('Tile', 'targets', 'pos-home-tile-render'), + codeblock: generateJsxCodeBlock( + '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: 'Tile', + subCategory: 'Smart grid', isVisualComponent: false, - related: [ - { - name: 'pos.home.modal.render', - url: '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 bccb874010..47cc0357c5 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 `shopify.action.presentModal()` to launch the companion modal for complete order workflows.', defaultExample: { codeblock: generateJsxCodeBlock( - '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: 'Action', + subCategory: 'Order details', isVisualComponent: false, - related: [ - { - name: ExtensionTargetType.PosOrderDetailsActionRender, - url: 'pos-order-details-action-render', - }, - { - name: ExtensionTargetType.PosOrderDetailsBlockRender, - url: '../block/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 93c46a5862..6e12205c46 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: generateJsxCodeBlock( - 'Order details action', + 'Create an order details action modal', 'targets', 'pos-order-details-action-render', ), + description: + 'Build a full-screen modal workflow launched from an order details action menu item. This example demonstrates creating order-specific experiences with multi-step processes, forms, and order data access for operations like refund processing or fulfillment management.', }, category: 'Targets', - subCategory: 'Action', + subCategory: 'Order details', isVisualComponent: false, - related: [ - { - name: ExtensionTargetType.PosOrderDetailsActionMenuItemRender, - url: 'pos-order-details-action-menu-item-render', - }, - { - name: ExtensionTargetType.PosOrderDetailsBlockRender, - url: '../block/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 ffafe14627..06657a6b2e 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 `shopify.action.presentModal()` for more complex order operations.', defaultExample: { codeblock: generateJsxCodeBlock( - 'Block', + 'Create an order details information block', 'targets', 'pos-order-details-block-render', ), + description: + 'Add a custom information section to the order details screen for displaying supplementary order data. This example shows how to create a block that provides additional order information, tracking details, or order-specific status alongside standard order details.', }, category: 'Targets', - subCategory: 'Block', + subCategory: 'Order details', isVisualComponent: false, - related: [ - { - name: ExtensionTargetType.PosOrderDetailsActionMenuItemRender, - url: '../action/pos-order-details-action-menu-item-render', - }, - { - name: ExtensionTargetType.PosOrderDetailsActionRender, - url: '../action/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 64c4c45b55..bd85ec64f9 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 `shopify.action.presentModal()` to launch the companion modal for complete product workflows.', defaultExample: { codeblock: generateJsxCodeBlock( - '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 integration with external systems.', }, category: 'Targets', - subCategory: 'Action', + subCategory: 'Product details', isVisualComponent: false, - related: [ - { - name: ExtensionTargetType.PosProductDetailsActionRender, - url: 'pos-product-details-action-render', - }, - { - name: ExtensionTargetType.PosProductDetailsBlockRender, - url: '../block/pos-product-details-block-render', - }, - { - name: 'ProductAPI', - url: '../../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 59f02d8412..e58bbdf285 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,31 +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: generateJsxCodeBlock( - 'Action', + 'Create a product details action modal', 'targets', 'product-details-action', ), + description: + 'Build a full-screen modal workflow launched from a product details action menu item. This example demonstrates creating product-specific experiences with multi-step processes, forms, and product data access for operations like inventory management or product customization.', }, category: 'Targets', - subCategory: 'Action', + subCategory: 'Product details', isVisualComponent: false, - related: [ - { - name: ExtensionTargetType.PosProductDetailsActionMenuItemRender, - url: 'pos-product-details-action-menu-item-render', - }, - { - name: ExtensionTargetType.PosProductDetailsBlockRender, - url: 'pos-product-details-block-render', - }, - { - name: 'ProductAPI', - url: '../../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 f0d104abfa..84c5cd185f 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 `shopify.action.presentModal()` for more complex product operations.', defaultExample: { codeblock: generateJsxCodeBlock( - 'Block', + 'Create a product details information block', 'targets', 'pos-product-details-block-render', ), + description: + 'Add a custom information section to the product details screen for displaying supplementary product data. This example shows how to create a block that provides additional product information, inventory status, or custom product attributes alongside standard product details.', }, category: 'Targets', - subCategory: 'Block', + subCategory: 'Product details', isVisualComponent: false, - related: [ - { - name: ExtensionTargetType.PosProductDetailsActionMenuItemRender, - url: '../action/pos-product-details-action-menu-item-render', - }, - { - name: ExtensionTargetType.PosProductDetailsActionRender, - url: '../action/pos-product-details-action-render', - }, - { - name: 'ProductAPI', - url: '../../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 d13d16d385..7388d0eaf0 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 `shopify.action.presentModal()` to launch the companion modal for complete post-purchase workflows.', defaultExample: { codeblock: generateJsxCodeBlock( - '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: 'Action', + subCategory: 'Post-purchase', isVisualComponent: false, - related: [ - { - name: ExtensionTargetType.PosPurchasePostActionRender, - url: 'pos-purchase-post-action-render', - }, - { - name: ExtensionTargetType.PosPurchasePostBlockRender, - url: '../block/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 245d760b36..408e6ee48b 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: generateJsxCodeBlock( - 'Action', + 'Create a post-purchase action modal', 'targets', 'pos-purchase-post-action-render', ), + description: + 'Build a full-screen modal workflow launched from a post-purchase action menu item. This example demonstrates creating complex post-purchase experiences with multi-step processes, forms, and order data access for operations like receipt customization or customer engagement.', }, category: 'Targets', - subCategory: 'Action', + subCategory: 'Post-purchase', isVisualComponent: false, - related: [ - { - name: ExtensionTargetType.PosPurchasePostActionMenuItemRender, - url: 'pos-purchase-post-action-menu-item-render', - }, - { - name: ExtensionTargetType.PosPurchasePostBlockRender, - url: '../block/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 68814734f6..e7a033e6f4 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 `shopify.action.presentModal()` for more complex post-purchase operations.', defaultExample: { codeblock: generateJsxCodeBlock( - 'Block', + 'Create a post-purchase information block', 'targets', 'pos-purchase-post-block-render', ), + description: + 'Add a custom information section to the post-purchase screen for displaying order details or status. This example shows how to create a block that provides supplementary information after completing a sale, with interactive elements that can launch modal workflows.', }, category: 'Targets', - subCategory: 'Block', + subCategory: 'Post-purchase', isVisualComponent: false, - related: [ - { - name: ExtensionTargetType.PosPurchasePostActionMenuItemRender, - url: '../action/pos-purchase-post-action-menu-item-render', - }, - { - name: ExtensionTargetType.PosPurchasePostActionRender, - url: '../action/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 091350e7de..c173d86454 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,18 +5,20 @@ 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: generateJsxCodeBlock( - 'Receipt Footer Block', + 'Create a receipt footer block', 'targets', 'pos-receipt-footer-block-render', ), + description: + 'Add a custom section to the footer of printed receipts for contact information, policies, or marketing. This example shows how to create a footer block that displays text content optimized for print formatting, useful for return policies, social media links, or customer engagement elements.', }, category: 'Targets', - subCategory: 'Block', + subCategory: 'Receipt', isVisualComponent: false, related: [], type: 'Target', diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.receipt-header.block.render.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.receipt-header.block.render.doc.ts index 299e5bdc60..979fe6207b 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.receipt-header.block.render.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.receipt-header.block.render.doc.ts @@ -5,18 +5,20 @@ import {ExtensionTargetType} from '../types/ExtensionTargetType'; const data: ReferenceEntityTemplateSchema = { name: ExtensionTargetType.PosReceiptHeaderBlockRender, - description: `Renders a custom section within the POS receipt header - > 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 header of printed receipts. Use this target for adding custom branding, logos, promotional messages, or store-specific information at the top of receipts.' + + '\n\nExtensions at this target appear in the receipt header area and support limited components optimized for print formatting, including text content for information display.', defaultExample: { codeblock: generateJsxCodeBlock( - 'Receipt Header Block', + 'Create a receipt header block', 'targets', 'pos-receipt-header-block-render', ), + description: + 'Add a custom section to the header of printed receipts for branding or important information. This example shows how to create a header block that displays text content optimized for print formatting, useful for store branding, promotional messages, or important notices at the top of receipts.', }, category: 'Targets', - subCategory: 'Block', + subCategory: 'Receipt', isVisualComponent: false, related: [], type: 'Target', diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.return.post.action.menu-item.render.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.return.post.action.menu-item.render.doc.ts index 187eb526e5..749e0082eb 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.return.post.action.menu-item.render.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.return.post.action.menu-item.render.doc.ts @@ -4,33 +4,22 @@ import {ExtensionTargetType} from '../types/ExtensionTargetType'; const data: ReferenceEntityTemplateSchema = { name: ExtensionTargetType.PosReturnPostActionMenuItemRender, - description: `A static extension target that renders as a menu item on the post-return screen - > 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 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.' + + '\n\nExtensions at this target can access the order identifier through the Order API to perform return-specific operations. Menu items typically invoke `shopify.action.presentModal()` to launch the companion modal for complete post-return workflows.', defaultExample: { codeblock: generateJsxCodeBlock( - 'Return Post Action Menu Item', + 'Create a post-return action menu item', 'targets', 'pos-return-post-action-menu-item-render', ), + description: + 'Add an interactive menu item to the post-return action menu for operations after completing a return. This example shows how to create a menu item that accesses order data and launches modal workflows for tasks like generating return receipts, processing restocking, or collecting feedback.', }, category: 'Targets', - subCategory: 'Action', + subCategory: 'Post-return', isVisualComponent: false, - related: [ - { - name: ExtensionTargetType.PosReturnPostActionRender, - subtitle: 'Target', - type: 'blocks', - url: 'pos-return-post-action-render', - }, - { - name: ExtensionTargetType.PosReturnPostBlockRender, - subtitle: 'Target', - type: 'blocks', - url: '../block/pos-return-post-block-render', - }, - ], + related: [], type: 'Target', }; diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.return.post.action.render.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.return.post.action.render.doc.ts index d56c6b956d..418f59e004 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.return.post.action.render.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.return.post.action.render.doc.ts @@ -4,34 +4,22 @@ import {ExtensionTargetType} from '../types/ExtensionTargetType'; const data: ReferenceEntityTemplateSchema = { name: ExtensionTargetType.PosReturnPostActionRender, - description: `A full-screen extension target that renders when a \`pos.return.post.action.menu-item.render\` target calls for it - - > 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 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.' + + '\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: generateJsxCodeBlock( - 'Return Post Action', + 'Create a post-return action modal', 'targets', 'pos-return-post-action-render', ), + description: + 'Build a full-screen modal workflow launched from a post-return action menu item. This example demonstrates creating complex post-return experiences with multi-step processes, forms, and order data access for operations like restocking workflows or return analytics.', }, category: 'Targets', - subCategory: 'Action', + subCategory: 'Post-return', isVisualComponent: false, - related: [ - { - name: ExtensionTargetType.PosReturnPostActionMenuItemRender, - subtitle: 'Target', - type: 'blocks', - url: 'pos-return-post-action-menu-item-render', - }, - { - name: ExtensionTargetType.PosReturnPostBlockRender, - subtitle: 'Target', - type: 'blocks', - url: '../block/pos-return-post-block-render', - }, - ], + related: [], type: 'Target', }; diff --git a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.return.post.block.render.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.return.post.block.render.doc.ts index 010d864c7b..d40a27c3f5 100644 --- a/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.return.post.block.render.doc.ts +++ b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/targets/pos.return.post.block.render.doc.ts @@ -4,33 +4,22 @@ import {ExtensionTargetType} from '../types/ExtensionTargetType'; const data: ReferenceEntityTemplateSchema = { name: ExtensionTargetType.PosReturnPostBlockRender, - description: `Renders a custom section within the native post return screen - > 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 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.' + + '\n\nExtensions at this target appear as persistent blocks within the post-return interface and support interactive elements that can launch modal workflows using `shopify.action.presentModal()` for more complex post-return operations.', defaultExample: { codeblock: generateJsxCodeBlock( - 'Return Post Block', + 'Create a post-return information block', 'targets', 'pos-return-post-block-render', ), + description: + 'Add a custom information section to the post-return screen for displaying return details or status. This example shows how to create a block that provides supplementary information after completing a return, with interactive elements that can launch modal workflows.', }, category: 'Targets', - subCategory: 'Block', + subCategory: 'Post-return', isVisualComponent: false, - related: [ - { - name: ExtensionTargetType.PosReturnPostActionMenuItemRender, - subtitle: 'Target', - type: 'blocks', - url: '../action/pos-return-post-action-menu-item-render', - }, - { - name: ExtensionTargetType.PosReturnPostActionRender, - subtitle: 'Target', - type: 'blocks', - url: '../action/pos-return-post-action-render', - }, - ], + related: [], type: 'Target', }; diff --git a/packages/ui-extensions/src/shared.ts b/packages/ui-extensions/src/shared.ts index 24fa8bbdd8..5310475b22 100644 --- a/packages/ui-extensions/src/shared.ts +++ b/packages/ui-extensions/src/shared.ts @@ -940,15 +940,15 @@ export interface GraphQLError { } /** - * Represents a read-only value managed on the main thread that an extension can subscribe to. - * - * Example: Checkout uses this to manage the state of an object and - * communicate state changes to extensions running in a sandboxed web worker. - * - * This interface is compatible with [Preact's ReadonlySignal](https://github.com/preactjs/signals/blob/a023a132a81bd4ba4a0bebb8cbbeffbd8c8bbafc/packages/core/src/index.ts#L700-L709). - * + * Represents a reactive signal interface that provides both immediate value access and subscription-based updates. Enables real-time synchronization with changing data through the observer pattern. */ export interface ReadonlySignalLike { + /** + * The current value of the locale string in IETF format. For example, `"en-US"`, `"fr-CA"`, or `"de-DE"`. This property provides immediate access to the current locale without requiring subscription setup. Use for one-time locale checks or initial internationalization setup. + */ readonly value: T; + /** + * Subscribes to locale changes and calls the provided function whenever the locale updates. Returns an unsubscribe function to clean up the subscription. Use to automatically update your extension content when merchants change their language settings during POS sessions. + */ subscribe(fn: (value: T) => void): () => void; } diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/api/action-api/action-api.ts b/packages/ui-extensions/src/surfaces/point-of-sale/api/action-api/action-api.ts index 39bafe47b3..b772c8a9eb 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/api/action-api/action-api.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/api/action-api/action-api.ts @@ -1,14 +1,12 @@ export interface ActionApiContent { - /** Presents the corresponding `.action.render` extension target as a modal overlay. - * - * For example: if we are calling presentModal() from pos.purchase.post.action.menu-item.render, - * it will 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 `shopify.action` to launch full-screen modal experiences. */ export interface ActionApi { action: ActionApiContent; diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/api/cart-api/cart-api.ts b/packages/ui-extensions/src/surfaces/point-of-sale/api/cart-api/cart-api.ts index 89fdaeee6f..a52cbe4914 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/api/cart-api/cart-api.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/api/cart-api/cart-api.ts @@ -11,31 +11,38 @@ 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 `shopify.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 read-only access to the current cart state and allows subscribing to cart changes. - * The `value` property provides the current cart state, and `subscribe` allows listening to changes. + * Provides read-only access to the current cart state and allows subscribing to cart changes. The `value` property provides the current cart state, and `subscribe` allows listening to changes with improved performance and memory management. */ current: ReadonlySignalLike; - /** 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 @@ -48,84 +55,82 @@ export interface CartApiContent { ): 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. - * Returns the uuid of the line item added, or the empty string if the user dismissed an oversell guard modal without adding anything. - * Throws if POS fails to add the line item. Throws if POS fails to add the line item. + * 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, or the empty string if the user dismissed an oversell guard modal + * @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 @@ -136,7 +141,7 @@ export interface CartApiContent { ): 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. */ @@ -145,7 +150,7 @@ export interface CartApiContent { ): 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 @@ -153,7 +158,7 @@ export interface CartApiContent { 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') @@ -168,7 +173,7 @@ export interface CartApiContent { ): 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. */ @@ -177,14 +182,14 @@ export interface CartApiContent { ): 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. @@ -195,35 +200,35 @@ export interface CartApiContent { ): 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; /** - * Add a selling plan to a line item in the cart. + * Add a selling plan to a line item in the cart using the line item `UUID`, selling plan `ID`, and selling plan name. Optionally provide delivery interval and interval count for improved performance, otherwise POS will fetch them after syncing the cart. * * @param uuid the uuid of the line item that should receive the selling plan * @param sellingPlanId the ID of the selling plan to add to the line item @@ -231,7 +236,7 @@ export interface CartApiContent { addLineItemSellingPlan(input: SetLineItemSellingPlanInput): Promise; /** - * Remove the selling plan from a line item in the cart. + * Remove the selling plan from a line item in the cart using the line item `UUID`. This will clear any subscription or recurring purchase configuration from the line item. * * @param uuid the uuid of the line item whose selling plan should be removed */ diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/api/cart-line-item-api/cart-line-item-api.ts b/packages/ui-extensions/src/surfaces/point-of-sale/api/cart-line-item-api/cart-line-item-api.ts index d3ac7bd9bd..38c4d633c8 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/api/cart-line-item-api/cart-line-item-api.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/api/cart-line-item-api/cart-line-item-api.ts @@ -1,11 +1,11 @@ import type {LineItem} from '../../types/cart'; /** - * Access to the selected line item in the merchant’s current cart. + * The `CartLineItemApi` object provides access to the current line item. Access this property through `api.cartLineItem` to interact with the current line item context. */ export interface CartLineItemApi { /** - * The selected line item in the merchant’s current cart. + * The selected line item in the merchant's current cart. Provides complete line item data including product information, pricing, discounts, properties, and metadata. Use for displaying item details and implementing item-specific functionality. */ cartLineItem: LineItem; } diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/api/connectivity-api/connectivity-api.ts b/packages/ui-extensions/src/surfaces/point-of-sale/api/connectivity-api/connectivity-api.ts index e9e0d5df5e..66f7ebe32a 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/api/connectivity-api/connectivity-api.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/api/connectivity-api/connectivity-api.ts @@ -2,23 +2,25 @@ import type {ReadonlySignalLike} from '../../../../shared'; 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 + * The Internet connection status of the POS device. */ internetConnected: ConnectivityStateSeverity; } export interface ConnectivityApiContent { /** - * Provides read-only access to the current connectivity state and allows subscribing to connectivity changes. - * The `value` property provides the current connectivity state, and `subscribe` allows listening to changes. + * Provides read-only access to the current connectivity state and allows subscribing to connectivity changes. Use for implementing connectivity-aware functionality and reactive connectivity handling. */ current: ReadonlySignalLike; } /** - * Access information about the device connectivity + * The `ConnectivityApi` object provides access to current connectivity information and change notifications. Access these properties through `shopify.connectivity` to monitor network status. */ export interface ConnectivityApi { connectivity: ConnectivityApiContent; diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/api/customer-api/customer-api.ts b/packages/ui-extensions/src/surfaces/point-of-sale/api/customer-api/customer-api.ts index cf7f811aa9..36b23b094c 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/api/customer-api/customer-api.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/api/customer-api/customer-api.ts @@ -1,10 +1,13 @@ +/** + * The `CustomerApi` object provides access to customer data in customer-specific extension contexts. Access this property through `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/api/device-api/device-api.ts b/packages/ui-extensions/src/surfaces/point-of-sale/api/device-api/device-api.ts index ce49af2a2a..cca4923b8f 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/api/device-api/device-api.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/api/device-api/device-api.ts @@ -1,20 +1,20 @@ export interface DeviceApiContent { /** - * The name of the device + * The name of the device as configured by the merchant or system. Use for displaying device information in interfaces, logging, or support contexts where device identification is helpful. */ name: string; /** - * The string ID of the device + * Retrieves the unique string identifier for the device. Returns a promise that resolves to the device ID. Use for device-specific data storage, analytics tracking, or implementing device-based permissions and configurations. */ getDeviceId(): Promise; /** - * Whether the device is a tablet + * Determines whether the device is a tablet form factor. Returns a promise that resolves to `true` for tablets, `false` for other device types. Use for implementing responsive design, optimizing touch targets, or providing device-appropriate user experiences. */ isTablet(): Promise; } /** - * Access information about the device, like name and ID + * The `DeviceApi` object provides access to device information and capabilities. Access these properties and methods through `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/api/draft-order-api/draft-order-api.ts b/packages/ui-extensions/src/surfaces/point-of-sale/api/draft-order-api/draft-order-api.ts index 83f2d88339..c3f9f73c36 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/api/draft-order-api/draft-order-api.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/api/draft-order-api/draft-order-api.ts @@ -1,20 +1,23 @@ +/** + * The `DraftOrderApi` object provides access to draft order data in draft order-specific extension contexts. Access this property through `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/api/locale-api/locale-api.ts b/packages/ui-extensions/src/surfaces/point-of-sale/api/locale-api/locale-api.ts index 5f40364a52..3b5efe676e 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/api/locale-api/locale-api.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/api/locale-api/locale-api.ts @@ -2,14 +2,13 @@ import type {ReadonlySignalLike} from '../../../../shared'; export interface LocaleApiContent { /** - * Provides read-only access to the current IETF-formatted locale and allows subscribing to locale changes. - * The `value` property provides the current locale, and `subscribe` allows listening to changes. + * Provides read-only access to the current IETF-formatted locale and allows subscribing to locale changes. The `value` property provides the current locale, and `subscribe` allows listening to changes. Use for internationalization, locale-specific formatting, and reactive updates when merchants change language settings. */ current: ReadonlySignalLike; } /** - * 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 `shopify.locale` to retrieve and monitor locale data. */ export interface LocaleApi { locale: LocaleApiContent; diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/api/navigation-api/navigation-api.ts b/packages/ui-extensions/src/surfaces/point-of-sale/api/navigation-api/navigation-api.ts index 10d5428f94..62ce4ce8da 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/api/navigation-api/navigation-api.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/api/navigation-api/navigation-api.ts @@ -1,44 +1,52 @@ +/** + * Specifies configuration options for navigation operations. Allows passing state data that persists across navigation transitions. + */ export interface NavigationNavigateOptions { /** - * Developer-defined information to be stored in the associated NavigationHistoryEntry once the navigation is complete, retrievable via getState(). + * Developer-defined information to be stored in the associated `NavigationHistoryEntry` once the navigation is complete, retrievable using `getState()`. Use to pass data between navigation states or implement stateful navigation workflows. */ state?: unknown; } /** - * The NavigationHistoryEntry interface of the Navigation API represents a single navigation history entry. + * Represents a single entry in the navigation history stack. Contains the URL and unique identifier for tracking navigation state and implementing history-based navigation. */ export interface NavigationHistoryEntry { - /** Returns the key of the history entry. This is a unique, UA-generated value that represents the history entry's slot in the entries list rather than the entry itself. */ + /** + * A unique, UA-generated value that represents the history entry's slot in the entries list rather than the entry itself. Use for tracking navigation history or implementing navigation-based logic. + */ key: string; /** - * Returns the URL of this history entry. + * The URL of this history entry. Returns `null` if no URL is associated with the entry. Use for URL-based navigation logic, deep-linking, or displaying current location information. */ url: string | null; /** - * Returns a clone of the available state associated with this history entry. + * Returns a clone of the available state associated with this history entry. Use to retrieve navigation state data that was passed during navigation or to implement state-based navigation logic. */ getState(): unknown; } export interface Navigation { /** - * The navigate() method navigates to a specific URL, updating any provided state in the history entries list. + * Navigates to a specific URL, updating any provided state in the history entries list. Returns a promise that resolves when navigation is complete. Use for programmatic navigation between screens, implementing custom navigation controls, or deep-linking to specific modal states. */ navigate: (url: string, options?: NavigationNavigateOptions) => Promise; /** - * The currentEntry read-only property of the Navigation interface returns a NavigationHistoryEntry object representing the location the user is currently navigated to right now. + * Returns a `NavigationHistoryEntry` object representing the location the user is currently navigated to. Use to access current URL, navigation state, or implement navigation-aware functionality based on the current location. */ currentEntry: NavigationHistoryEntry; /** - * The back() method of the Navigation interface navigates to the previous entry in the history list. + * Navigates to the previous entry in the history list. Use for implementing back buttons, breadcrumb navigation, or allowing users to return to previous screens in multi-step workflows. */ back(): void; } +/** + * The global `window` object provides control over the extension modal lifecycle. Access these properties and methods directly through the global `window` object to manage the modal interface programmatically. + */ export interface Window { /** - * The close() method of the window interface closes the extension screen. + * Closes the extension screen and dismisses the modal interface. Use to programmatically close the modal after completing a workflow, canceling an operation, or when user action is no longer required. This provides the same behavior as the user dismissing the modal through the UI. */ close(): void; } diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/api/order-api/order-api.ts b/packages/ui-extensions/src/surfaces/point-of-sale/api/order-api/order-api.ts index 8cbd6af9e5..349f6308f0 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/api/order-api/order-api.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/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/api/pin-pad-api.ts b/packages/ui-extensions/src/surfaces/point-of-sale/api/pin-pad-api.ts index f293296471..66f2bbac53 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/api/pin-pad-api.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/api/pin-pad-api.ts @@ -1,18 +1,14 @@ import {PinPadOptions, PinValidationResult} from '../types/pin-pad'; export interface PinPadApiContent { - /** Shows a PIN pad to the user in a modal dialog. + /** + * Shows a PIN pad to the user in a modal dialog. The `onSubmit` function is called when the PIN is submitted and should validate the PIN, returning `'accept'` or `'reject'`. * - * `onSubmit` is called when the PIN is submitted for validation by the user. The callback - * should validate the PIN and accept or reject it. + * • **When accepted**: Modal dismisses and triggers the `onDismissed` callback—perform any post-validation navigation in this callback rather than in `onSubmit`. * - * If the PIN is accepted, the modal will be dismissed and the `onDismissed` callback - * (provided via `options`) will be called. It is recommended that any post-validation - * navigation is performed in this callback rather than in `onSubmit`. - * - * If the PIN is rejected, the optional `errorMessage` will be displayed to the user and the modal - * will not be dismissed. + * • **When rejected**: Displays the optional `errorMessage` and keeps the modal open. * + * Use for implementing secure authentication workflows, access control, or PIN-based verification systems. */ showPinPad( onSubmit: ( @@ -23,7 +19,7 @@ export interface PinPadApiContent { } /** - * Access the PIN Pad API for PIN pad functionality in a modal. + * The `PinPadApi` object provides methods for displaying secure PIN entry interfaces. Access these methods through `shopify.pinPad` to show PIN pad modals and handle PIN validation. */ export interface PinPadApi { pinPad: PinPadApiContent; diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/api/print-api/print-api.ts b/packages/ui-extensions/src/surfaces/point-of-sale/api/print-api/print-api.ts index 62f275454e..44912bebfe 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/api/print-api/print-api.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/api/print-api/print-api.ts @@ -1,19 +1,15 @@ /** - * Access the print API for printing functionality + * The `PrintApi` object provides methods for triggering document printing. Access these methods through `shopify.print` to initiate print operations with various document types. */ 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 full URL to your app's backend that will be used to return the document to print + * • A relative path that will be appended to your app's [`application_url`](/docs/apps/build/cli-for-apps/app-configuration) * - * 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) + * • A full URL to your app's backend that will be used to return the document to print + * + * Returns a promise that resolves when content is ready and the native print dialog appears. Use for printing custom documents, receipts, labels, or reports. * * @param src the source URL of the content to print. * @returns Promise that resolves when content is ready and native print dialog appears. @@ -22,8 +18,11 @@ export interface PrintApiContent { } /** - * Interface for printing + * The `PrintApi` object provides methods for triggering document printing. Access these methods through `shopify.print` to initiate print operations with various document types. */ export interface PrintApi { + /** + * The `PrintApi` object provides methods for triggering document printing. Access these methods through `shopify.print` to initiate print operations with various document types. + */ print: PrintApiContent; } diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/api/product-api/product-api.ts b/packages/ui-extensions/src/surfaces/point-of-sale/api/product-api/product-api.ts index a73bb0d882..6e602ad935 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/api/product-api/product-api.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/api/product-api/product-api.ts @@ -1,14 +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. + * The unique identifier for the product variant. Use for variant-specific operations, cart additions, and inventory management. */ variantId: number; } diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/api/product-search-api/product-search-api.ts b/packages/ui-extensions/src/surfaces/point-of-sale/api/product-search-api/product-search-api.ts index c34be83fbb..23dddd9c6e 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/api/product-search-api/product-search-api.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/api/product-search-api/product-search-api.ts @@ -9,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 `shopify.productSearch` to search products and fetch detailed product data. */ export interface ProductSearchApi { productSearch: ProductSearchApiContent; diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/api/scanner-api/scanner-api.ts b/packages/ui-extensions/src/surfaces/point-of-sale/api/scanner-api/scanner-api.ts index 8a7998b4ce..ea831d578b 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/api/scanner-api/scanner-api.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/api/scanner-api/scanner-api.ts @@ -3,40 +3,58 @@ import type {ReadonlySignalLike} from '../../../../shared'; /** 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'` - Built-in device camera used for scanning + * • `'external'` - External scanner hardware connected to the device + * • `'embedded'` - Embedded scanner hardware built into the device + */ source?: ScannerSource; } +/** + * Represents the available scanner hardware sources on the device. Provides reactive access to the list of scanners that can be used for scanning operations. + */ export interface ScannerSources { /** - * The current available scanner sources. - * The `value` property provides the current sources, and `subscribe` allows listening to changes. + * Current available scanner sources with subscription support. The `value` property provides current sources, and `subscribe` listens for changes. Use to monitor which scanners are available. */ current: ReadonlySignalLike; } +/** + * Represents the scanner interface for accessing scan events and subscription management. Provides real-time access to scanned data through a reactive signal pattern. + */ export interface ScannerData { /** - * The current scan data. - * The `value` property provides the current scan result, and `subscribe` allows listening to new scans. + * Current available scanner sources with subscription support. The `value` property provides current sources, and `subscribe` listens for changes. Use to monitor which scanners are available. */ current: ReadonlySignalLike; } export interface ScannerApiContent { /** - * Provides read-only access to scanner data and allows subscribing to new scan events. + * Access current scan data and subscribe to new scan events. Use to receive real-time scan results. */ scannerData: ScannerData; /** - * Provides read-only access to the available scanner sources on the POS device. + * Access available scanner sources on the device. Use to check which scanners are available (camera, external, or embedded). */ sources: ScannerSources; } +/** + * The `ScannerApi` object provides access to scanning functionality and scanner source information. Access these properties through `shopify.scanner` to monitor scan events and available scanner sources. + */ export interface ScannerApi { scanner: ScannerApiContent; } diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/api/session-api/session-api.ts b/packages/ui-extensions/src/surfaces/point-of-sale/api/session-api/session-api.ts index 99e9c3f20b..488f88cc2d 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/api/session-api/session-api.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/api/session-api/session-api.ts @@ -2,20 +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. - * When the authenticated user (the user that logged into Shopify POS with their email address) doesn't have the correct app permissions enabled for your app, null will be returned. This is irrelevant of which POS Staff member is pinned in, as those are not authenticated users. - * For more information, see our [app permissions documentation](https://help.shopify.com/en/manual/your-account/users/roles/permissions/store-permissions#apps-and-channels-permissions). - * 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/api/storage-api/storage-api.ts b/packages/ui-extensions/src/surfaces/point-of-sale/api/storage-api/storage-api.ts index 7fdd061508..8bc80cf7c1 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/api/storage-api/storage-api.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/api/storage-api/storage-api.ts @@ -1,5 +1,8 @@ import {Storage} from '../../types/storage'; +/** + * The `StorageApi` object provides access to persistent local storage methods for your POS UI extension. Access these methods through `shopify.storage` to store, retrieve, and manage data that persists across sessions. + */ export interface StorageApi { storage: Storage; } diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/api/toast-api/toast-api.ts b/packages/ui-extensions/src/surfaces/point-of-sale/api/toast-api/toast-api.ts index 160d8651a8..740a133042 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/api/toast-api/toast-api.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/api/toast-api/toast-api.ts @@ -1,16 +1,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/components.d.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components.d.ts index b57d1c52c8..f0574d1555 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components.d.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components.d.ts @@ -12,84 +12,101 @@ * TODO: Update `any` type here after this is resolved * https://github.com/Shopify/ui-api-design/issues/139 */ +/** + * Represents any valid child content that can be rendered within a component. + */ export type ComponentChildren = any; +/** + * Represents text-only child content. + */ export type StringChildren = string; +/** + * Properties that are available on all components. + */ export interface GlobalProps { /** - * A unique identifier for the element. + * A unique identifier for the element within the document. This ID is used for multiple purposes: targeting the element from JavaScript code, creating relationships between elements (using `commandFor`, `interestFor`, ARIA attributes), linking labels to form controls, enabling fragment navigation with URL anchors (for example, `#section-id`), and applying element-specific styles. The ID must be unique across the entire page—duplicate IDs will cause unexpected behavior and accessibility issues. Use descriptive, semantic IDs that indicate the element's purpose (for example, `"checkout-button"`, `"main-nav"`, `"product-details-modal"`) rather than generic numbers or arbitrary strings. IDs are case-sensitive and should only contain letters, digits, hyphens, and underscores. If you don't need to reference the element externally, you can omit the ID. */ id?: string; } +/** + * Provides slots for primary and secondary action elements. + */ export interface ActionSlots { /** - * The primary action to perform, provided as a button or link type element. + * The primary action element to display, typically a `Button` or clickable link representing the most important action the user can take in the current context. This action should align with the user's primary goal or the main purpose of the interface. For example, "Save changes", "Checkout", "Add to cart", or "Submit order". The primary action typically receives visual emphasis through styling to draw user attention. Only one primary action should be provided to avoid confusion about the main call-to-action. If no primary action is needed, omit this property rather than providing an empty or placeholder action. */ primaryAction?: ComponentChildren; /** - * The secondary actions to perform, provided as button or link type elements. + * Secondary action elements to display, typically `Button` or clickable link elements representing alternative or supporting actions that are less important than the primary action. These might include "Cancel", "Save draft", "Skip", "Learn more", or other optional actions. Secondary actions receive less visual prominence than the primary action to maintain clear hierarchy. Multiple secondary actions can be provided and will typically be displayed together, often in a different visual style or position than the primary action. If no secondary actions are needed, omit this property. The order of actions in the array may affect their display order depending on the component. */ secondaryActions?: ComponentChildren; } +/** + * Properties for overlay lifecycle callbacks. + */ export interface BaseOverlayProps { /** - * Callback fired after the overlay is shown. + * A callback function executed when the overlay begins to appear, immediately after `showOverlay()` is called or the `hidden` property changes to `false`, but before any show animations start. The element may not be visible yet. Use this for initializing overlay content, fetching data needed for display, setting focus on the first interactive element, or tracking analytics events for when users begin viewing the overlay. Avoid layout calculations here as the element may not have final dimensions yet. */ onShow?: (event: Event) => void; /** - * Callback fired when the overlay is shown **after** any animations to show the overlay have finished. + * A callback function executed after the overlay is fully visible and all show animations have completed. At this point, the overlay is completely rendered with final dimensions and positioning. Use this for operations that require the overlay to be fully displayed, such as focusing specific elements after animations complete, measuring rendered content dimensions, triggering secondary animations, or initializing interactive features that depend on final layout. This is the safest place for DOM measurements and layout-dependent operations. */ onAfterShow?: (event: Event) => void; /** - * Callback fired after the overlay is hidden. + * A callback function executed when the overlay begins to hide, immediately after `hideOverlay()` is called or the `hidden` property changes to `true`, but before any hide animations start. The element is still visible. Use this for cleanup operations, saving overlay state before it disappears, canceling pending requests, or preparing for the post-hide state. This is your last opportunity to interact with the visible overlay before animations begin. */ onHide?: (event: Event) => void; /** - * Callback fired when the overlay is hidden **after** any animations to hide the overlay have finished. + * A callback function executed after the overlay is completely hidden and all hide animations have finished. The element is no longer visible or interactive. Use this for final cleanup, focusing the element that triggered the overlay, navigating to another view, freeing resources, or performing operations that should only occur after the overlay is completely dismissed. This is the appropriate place for post-dismissal navigation or state updates that would be jarring if they occurred during animations. */ onAfterHide?: (event: Event) => void; } /** - * Shared interfaces for web component methods. - * - * Methods are required (not optional) because: + * Methods for controlling overlay visibility. These methods are required (not optional) because: * - Components implementing this interface must provide all methods - * - Unlike props/attributes, methods are not rendered in HTML but are JavaScript APIs + * - Unlike props/attributes, methods aren't rendered in HTML but are JavaScript APIs * - Consumers expect these methods to be consistently available on all instances */ export interface BaseOverlayMethods { /** - * Method to show an overlay. + * Programmatically displays the overlay element. When called, the overlay becomes visible and triggers any associated `onShow` and `onAfterShow` callbacks. Use this method to open modals, dialogs, or other overlay components in response to user actions or application state changes. * * @implementation This is a method to be called on the element and not a callback and should hence be camelCase */ showOverlay: () => void; /** - * Method to hide an overlay. + * Programmatically hides the overlay element. When called, the overlay becomes hidden and triggers any associated `onHide` and `onAfterHide` callbacks. Use this method to close modals, dismiss dialogs, or hide overlay components programmatically rather than waiting for user interaction. * * @implementation This is a method to be called on the element and not a callback and should hence be camelCase */ hideOverlay: () => void; /** - * Method to toggle the visiblity of an overlay. + * Programmatically toggles the overlay's visibility state. If currently visible, the overlay will be hidden; if currently hidden, it will be shown. This triggers the appropriate show/hide callbacks based on the resulting state. Use this method to create toggle buttons or cycle through overlay visibility states. * * @implementation This is a method to be called on the element and not a callback and should hence be camelCase */ toggleOverlay: () => void; } +/** + * Properties for focus event callbacks. + */ export interface FocusEventProps { /** - * Callback when the element loses focus. + * A callback function executed when focus is removed from the element, either by the user moving to another field (tabbing, clicking elsewhere) or programmatically using `blur()`. This event fires before `onChange` for modified fields. The event contains information about which element is receiving focus next (`relatedTarget`). Use this for triggering validation, saving in-progress changes, hiding related UI elements like autocomplete dropdowns, or tracking field interaction analytics. Common pattern: validate and show errors on blur to avoid disrupting users while they're still typing. * - * @see https://developer.mozilla.org/en-US/docs/Web/API/Element/blur_event + * Learn more about [blur events on MDN](https://developer.mozilla.org/en-US/docs/Web/API/Element/blur_event). */ onBlur?: (event: FocusEvent) => void; /** - * Callback when the element receives focus. - * - * @see https://developer.mozilla.org/en-US/docs/Web/API/Element/focus_event + * A callback function executed when the element receives focus through user interaction (clicking, tabbing) or programmatic methods like `focus()`. This event fires before any input occurs. The event contains information about which element previously had focus (`relatedTarget`). Use this for showing helper text, highlighting the active field, displaying related UI like autocomplete suggestions, preselecting content, or tracking which fields users interact with. Common pattern: clear errors on focus to provide a fresh start when users re-attempt input after validation failure. Learn more about [focus events on MDN](https://developer.mozilla.org/en-US/docs/Web/API/Element/focus_event). */ onFocus?: (event: FocusEvent) => void; } +/** + * Defines the available size options for icons using a semantic scale. Provides granular control over icon dimensions from compact inline sizes to prominent display sizes. + */ export type SizeKeyword = | 'small-500' | 'small-400' @@ -104,23 +121,27 @@ export type SizeKeyword = | 'large-300' | 'large-400' | 'large-500'; +/** + * Defines the available color intensity options for icons. Controls the visual prominence and contrast of icon elements within the interface. + */ export type ColorKeyword = 'subdued' | 'base' | 'strong'; +/** + * A background color keyword including transparent option. + */ export type BackgroundColorKeyword = 'transparent' | ColorKeyword; +/** + * Properties for controlling the background color of an element. + */ export interface BackgroundProps { /** - * Adjust the background of the element. + * Sets the background color intensity of the element. Controls how the element stands out from its surroundings. * * @default 'transparent' */ background?: BackgroundColorKeyword; } /** - * Tone is a property for defining the color treatment of a component. - * - * A tone can apply a grouping of colors to a component. For example, - * critical may have a specific text color and background color. - * - * In some cases, like for Banner, the tone may also affect the semantic and accessibility treatment of the component. + * Defines the semantic tone options for icons. Controls the color and visual emphasis based on the information type and importance being communicated. * * @default 'auto' */ @@ -683,17 +704,29 @@ declare const privateIconArray: readonly [ 'x-circle', 'x-circle-filled', ]; +/** + * A valid icon identifier from the available icon set. + */ export type IconType = (typeof privateIconArray)[number]; /** * Like `Extract`, but ensures that the extracted type is a strict subtype of the input type. */ export type ExtractStrict = Extract; +/** + * A utility type for properties that support [1-to-4-value shorthand syntax](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Cascade/Shorthand_properties#edges_of_a_box). + */ export type MaybeAllValuesShorthandProperty = | T | `${T} ${T}` | `${T} ${T} ${T}` | `${T} ${T} ${T} ${T}`; +/** + * Defines a shorthand property that accepts either a single value or two space-separated values for directional properties like padding and spacing. + */ export type MaybeTwoValuesShorthandProperty = T | `${T} ${T}`; +/** + * A utility type for values that can be responsive using container queries. + */ export type MaybeResponsive = T | `@container${string}`; /** * Prevents widening string literal types in a union to `string`. @@ -705,41 +738,42 @@ export type MaybeResponsive = T | `@container${string}`; */ export type AnyString = string & {}; /** - * This is purely to give the ability - * to have a space or not in the string literal types. + * A utility type that allows optional spacing in string literal values. * - * For example in the `aspectRatio` property, `16/9` and `16 / 9` are both valid. + * For example, in the `aspectRatio` property, `16/9` and `16 / 9` are both valid. */ export type optionalSpace = '' | ' '; export interface BadgeProps extends GlobalProps { /** - * The content of the Badge. + * The child elements to render within this component. */ children?: ComponentChildren; /** - * Sets the tone of the Badge, based on the intention of the information being conveyed. + * The semantic tone of the badge, based on the intention of the information being conveyed. Affects color and styling to communicate meaning. * * @default 'auto' */ tone?: ToneKeyword; /** - * Modify the color to be more or less intense. + * The color intensity of the badge. Controls how prominent or subtle the badge appears within the interface. * * @default 'base' */ color?: ColorKeyword; /** - * The type of icon to be displayed in the badge. + * The icon identifier specifying which icon to display within the badge. Accepts any valid icon name from the icon set. * * @default '' */ icon?: IconType | AnyString; /** - * The position of the icon in relation to the text. + * The position of the icon relative to the badge text content: + * - `'start'`: Icon appears before the text + * - `'end'`: Icon appears after the text */ iconPosition?: 'start' | 'end'; /** - * Adjusts the size. + * Adjusts the size of the badge and its icon. Available sizes range from `'small-500'` (smallest) through `'base'` (default) to `'large-500'` (largest), allowing you to match badge size to your interface hierarchy. * * @default 'base' */ @@ -747,60 +781,46 @@ export interface BadgeProps extends GlobalProps { } export interface BannerProps extends GlobalProps, ActionSlots { /** - * The title of the banner. + * The title text displayed prominently at the top of the banner. Should be concise and clearly communicate the main message or purpose of the banner. * * @default '' */ heading?: string; /** - * The content of the Banner. + * The child elements to render within this component. */ children?: ComponentChildren; /** - * Sets the tone of the Banner, based on the intention of the information being conveyed. - * - * The banner is a live region and the type of status will be dictated by the Tone selected. + * Sets the visual appearance and accessibility behavior of the banner. The tone determines both the color scheme and how screen readers announce the banner. Available options: + * - `'auto'` - Lets the system automatically choose the appropriate tone based on context + * - `'success'` - Green styling for positive outcomes and successful operations. Creates an informative live region for screen readers + * - `'info'` - Blue styling for general information and neutral updates. Creates an informative live region for screen readers + * - `'warning'` - Orange styling for important notices that require attention. Creates an informative live region for screen readers + * - `'critical'` - Red styling for errors and urgent issues requiring immediate action. Creates an assertive live region that is announced immediately by screen readers. * - * - `critical` creates an [assertive live region](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/alert_role) that is announced by screen readers immediately. - * - `neutral`, `info`, `success`, `warning` and `caution` creates an [informative live region](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/status_role) that is announced by screen readers after the current message. - * - * @see https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions - * @see https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/alert_role - * @see https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/status_role + * Learn more about [ARIA live regions](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions), [alert role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/alert_role), and [status role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/status_role) on MDN. * * @default 'auto' */ tone?: ToneKeyword; /** - * Makes the content collapsible. - * A collapsible banner will conceal child elements initially, but allow the user to expand the banner to see them. + * Whether the banner content can be collapsed and expanded. When `true`, the banner displays a collapse/expand toggle control and child elements are initially hidden. Users can click the toggle to reveal or hide the content. Use for lengthy banners or supplementary information that users can choose to view. Collapsed state persists during the component lifecycle but resets on re-render. * * @default false */ collapsible?: boolean; /** - * Determines whether the close button of the banner is present. - * - * When the close button is pressed, the `dismiss` event will fire, - * then `hidden` will be true, - * any animation will complete, - * and the `afterhide` event will fire. + * Whether a close button is displayed in the banner. When `true`, a close (X) button appears allowing users to permanently dismiss the banner. Once dismissed, the banner triggers the `onDismiss` callback and remains hidden until the component is re-rendered or the `hidden` property is changed. Use for non-critical notifications or messages that users can choose to dismiss after reading. * * @default false */ dismissible?: boolean; /** - * Event handler when the banner is dismissed by the user. - * - * This does not fire when setting `hidden` manually. - * - * The `hidden` property will be `false` when this event fires. + * A callback function executed when the user dismisses the banner by clicking the close (X) button. This only fires for user-initiated dismissals through the UI close button, not when the banner is hidden programmatically using the `hidden` property. The callback fires after the user clicks but before hide animations begin. Use this for tracking dismissal metrics, saving user preferences to avoid showing the banner again, performing cleanup when banners are dismissed, or triggering follow-up actions. The banner remains in the DOM after dismissal (just hidden) until re-rendered—to completely remove it, control rendering at the component level based on dismissal state. */ onDismiss?: (event: Event) => void; /** - * Event handler when the banner has fully hidden. - * - * The `hidden` property will be `true` when this event fires. + * A callback function executed after the element is fully hidden and all hide animations have completed. * * @implementation If implementations animate the hiding of the banner, * this event must fire after the banner has fully hidden. @@ -808,35 +828,30 @@ export interface BannerProps extends GlobalProps, ActionSlots { */ onAfterHide?: (event: Event) => void; /** - * Determines whether the banner is hidden. - * - * If this property is being set on each framework render (as in 'controlled' usage), - * and the banner is `dismissible`, - * ensure you update app state for this property when the `dismiss` event fires. - * - * If the banner is not `dismissible`, it can still be hidden by setting this property. + * Whether the banner is visible or hidden. When set to `true`, the banner is completely hidden from view and removed from the accessibility tree, meaning screen readers won't announce it. Changing this value triggers hide/show animations if configured. Unlike temporary dismissal with the close button, this provides programmatic control for conditional visibility based on application state, user permissions, or other dynamic conditions. * * @default false */ hidden?: boolean; } +/** + * Properties for controlling the display behavior of an element. + */ export interface DisplayProps { /** - * Sets the outer display type of the component. The outer type sets a component’s participation in [flow layout](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_flow_layout). - * - * - `auto`: the component’s initial value. The actual value depends on the component and context. - * - `none`: hides the component from display and removes it from the accessibility tree, making it invisible to screen readers. + * Sets the outer display type controlling the element's participation in flow layout. Use `'auto'` for default behavior or `'none'` to hide the element and remove it from the accessibility tree. + * Learn more about the [CSS display property on MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/display). * - * @see https://developer.mozilla.org/en-US/docs/Web/CSS/display * @default 'auto' */ display?: MaybeResponsive<'auto' | 'none'>; } +/** + * Properties for defining the semantic role of an element for assistive technologies. + */ export interface AccessibilityRoleProps { /** - * Sets the semantic meaning of the component’s content. When set, - * the role will be used by assistive technologies to help users - * navigate the page. + * Sets the semantic role for assistive technologies. Helps screen reader users navigate and understand page structure. * * @implementation Although, in HTML hosts, this property changes the element used, * changing this property must not impact the visual styling of inside or outside of the box. @@ -926,7 +941,7 @@ export type AccessibilityRole = */ | 'separator' /** - * Used to define a live region containing advisory information for the user that is not important enough to be an alert. + * Used to define a live region containing advisory information for the user that isn't important enough to be an alert. * * In an HTML host `status` will render as `
`. * Learn more about the [`status` role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/status_role) in the MDN web docs. @@ -940,44 +955,48 @@ export type AccessibilityRole = */ | 'alert' /** - * Used to create a nameless container element which has no semantic meaning on its own. + * Used to create a container element with no specific semantic meaning. * * In an HTML host `generic'` will render a `
` element. * Learn more about the [`generic` role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/generic_role) in the MDN web docs. */ | 'generic' /** - * Used to strip the semantic meaning of an element, but leave the visual styling intact. + * Used to remove semantic meaning from an element while preserving its visual styling. * * Synonym for `none` * Learn more about the [`presentation` role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/presentation_role) in the MDN web docs. */ | 'presentation' /** - * Used to strip the semantic meaning of an element, but leave the visual styling intact. + * Used to remove semantic meaning from an element while preserving its visual styling. * * Synonym for `presentation` * Learn more about the [`none` role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/none_role) in the MDN web docs. */ | 'none'; +/** + * Properties for controlling visibility to assistive technologies. + */ export interface AccessibilityVisibilityProps { /** - * Changes the visibility of the element. - * - * - `visible`: the element is visible to all users. - * - `hidden`: the element is removed from the accessibility tree but remains visible. - * - `exclusive`: the element is visually hidden but remains in the accessibility tree. + * Controls visibility for assistive technologies: + * - `'visible'`: Announced normally by screen readers + * - `'hidden'`: Hidden from screen readers while remaining visually visible + * - `'exclusive'`: Only this element is announced to screen readers, hiding other content * * @default 'visible' */ accessibilityVisibility?: 'visible' | 'hidden' | 'exclusive'; } +/** + * Properties for controlling the visibility of field labels to screen readers. + */ export interface LabelAccessibilityVisibilityProps { /** - * Changes the visibility of the component's label. - * - * - `visible`: the label is visible to all users. - * - `exclusive`: the label is visually hidden but remains in the accessibility tree. + * Controls whether the label is announced to screen readers: + * - `'visible'`: Label is announced normally by screen readers + * - `'exclusive'`: Only the label is announced, hiding other related content from screen readers * * @default 'visible' */ @@ -986,35 +1005,35 @@ export interface LabelAccessibilityVisibilityProps { 'visible' | 'exclusive' >; } +/** + * Defines the available padding size options using a semantic scale. Provides consistent spacing values that align with the POS design system. + */ export type PaddingKeyword = SizeKeyword | 'none'; +/** + * Properties for controlling the padding (internal spacing) of an element. + */ export interface PaddingProps { /** - * Adjust the padding of all edges. - * - * [1-to-4-value syntax](https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand_properties#edges_of_a_box) is - * supported. Note that, contrary to the CSS, it uses flow-relative values and the order is: + * The padding applied to all edges of the container. Supports [1-to-4-value syntax](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Cascade/Shorthand_properties#edges_of_a_box) using flow-relative values in the order: * * - 4 values: `block-start inline-end block-end inline-start` * - 3 values: `block-start inline block-end` * - 2 values: `block inline` * * For example: + * * - `large` means block-start, inline-end, block-end and inline-start paddings are `large`. * - `large none` means block-start and block-end paddings are `large`, inline-start and inline-end paddings are `none`. * - `large none large` means block-start padding is `large`, inline-end padding is `none`, block-end padding is `large` and inline-start padding is `none`. * - `large none large small` means block-start padding is `large`, inline-end padding is `none`, block-end padding is `large` and inline-start padding is `small`. * - * A padding value of `auto` will use the default padding for the closest container that has had its usual padding removed. + * An `auto` value inherits the default padding from the closest container that has removed its usual padding. * * @default 'none' */ padding?: MaybeResponsive>; /** - * Adjust the block-padding. - * - * - `large none` means block-start padding is `large`, block-end padding is `none`. - * - * This overrides the block value of `padding`. + * The block-axis padding for the container. Overrides the block value of the `padding` property. * * @default '' - meaning no override */ @@ -1022,27 +1041,19 @@ export interface PaddingProps { MaybeTwoValuesShorthandProperty | '' >; /** - * Adjust the block-start padding. - * - * This overrides the block-start value of `paddingBlock`. + * The block-start padding for the container. Overrides the block-start value of the `paddingBlock` property. * * @default '' - meaning no override */ paddingBlockStart?: MaybeResponsive; /** - * Adjust the block-end padding. - * - * This overrides the block-end value of `paddingBlock`. + * The block-end padding for the container. Overrides the block-end value of the `paddingBlock` property. * * @default '' - meaning no override */ paddingBlockEnd?: MaybeResponsive; /** - * Adjust the inline padding. - * - * - `large none` means inline-start padding is `large`, inline-end padding is `none`. - * - * This overrides the inline value of `padding`. + * The inline-axis padding for the container. Supports two-value syntax where `large none` sets inline-start to `large` and inline-end to `none`. Overrides the inline value of the `padding` property. * * @default '' - meaning no override */ @@ -1050,82 +1061,87 @@ export interface PaddingProps { MaybeTwoValuesShorthandProperty | '' >; /** - * Adjust the inline-start padding. - * - * This overrides the inline-start value of `paddingInline`. + * The inline-start padding for the container. Overrides the inline-start value of the `paddingInline` property. * * @default '' - meaning no override */ paddingInlineStart?: MaybeResponsive; /** - * Adjust the inline-end padding. - * - * This overrides the inline-end value of `paddingInline`. + * The inline-end padding for the container. Overrides the inline-end value of the `paddingInline` property. * * @default '' - meaning no override */ paddingInlineEnd?: MaybeResponsive; } +/** + * Defines exact size measurements without automatic or unconstrained options. Limited to specific pixel values, percentages, or zero. + */ export type SizeUnits = `${number}px` | `${number}%` | `0`; +/** + * Defines size values that can be specified as exact measurements or automatic sizing. Supports pixel values, percentages, zero, or automatic sizing based on content. + */ export type SizeUnitsOrAuto = SizeUnits | 'auto'; +/** + * Defines size values that can be specified as exact measurements or no constraint. Supports pixel values, percentages, zero, or no maximum limit. + */ export type SizeUnitsOrNone = SizeUnits | 'none'; +/** + * Properties for controlling the dimensions of an element. + */ export interface SizingProps { /** - * Adjust the block size. - * - * @see https://developer.mozilla.org/en-US/docs/Web/CSS/block-size + * The block size of the container. Auto automatically sizes based on the container's children. * * @default 'auto' */ blockSize?: MaybeResponsive; /** - * Adjust the minimum block size. - * - * @see https://developer.mozilla.org/en-US/docs/Web/CSS/min-block-size + * The minimum block size constraint for the container. * * @default '0' */ minBlockSize?: MaybeResponsive; /** - * Adjust the maximum block size. - * - * @see https://developer.mozilla.org/en-US/docs/Web/CSS/max-block-size + * The maximum block size constraint for the container. * * @default 'none' */ maxBlockSize?: MaybeResponsive; /** - * Adjust the inline size. - * - * @see https://developer.mozilla.org/en-US/docs/Web/CSS/inline-size + * The inline size of the container. Auto automatically sizes based on the container's children. * * @default 'auto' */ inlineSize?: MaybeResponsive; /** - * Adjust the minimum inline size. - * - * @see https://developer.mozilla.org/en-US/docs/Web/CSS/min-inline-size + * The minimum inline size constraint for the container. * * @default '0' */ minInlineSize?: MaybeResponsive; /** - * Adjust the maximum inline size. - * - * @see https://developer.mozilla.org/en-US/docs/Web/CSS/max-inline-size + * The maximum inline size constraint for the container. * * @default 'none' */ maxInlineSize?: MaybeResponsive; } +/** + * A border line style keyword. + */ export type BorderStyleKeyword = | 'none' | 'solid' | 'dashed' | 'dotted' | 'auto'; +/** + * A border thickness keyword. + */ export type BorderSizeKeyword = SizeKeyword | 'none'; +/** + * A border radius keyword including maximum rounding option. + */ export type BorderRadiusKeyword = SizeKeyword | 'max' | 'none'; /** * Represents a shorthand for defining a border. It can be a combination of size, optionally followed by color, optionally followed by style. @@ -1134,17 +1150,12 @@ export type BorderShorthand = | BorderSizeKeyword | `${BorderSizeKeyword} ${ColorKeyword}` | `${BorderSizeKeyword} ${ColorKeyword} ${BorderStyleKeyword}`; +/** + * Properties for controlling the border styling of an element. + */ export interface BorderProps { /** - * Set the border via the shorthand property. - * - * This can be a size, optionally followed by a color, optionally followed by a style. - * - * If the color is not specified, it will be `base`. - * - * If the style is not specified, it will be `auto`. - * - * Values can be overridden by `borderWidth`, `borderStyle`, and `borderColor`. + * Sets the border style, width, and color using shorthand syntax. Accepts a size keyword, optionally followed by a color keyword, optionally followed by a style keyword. * * @example * // The following are equivalent: @@ -1155,82 +1166,49 @@ export interface BorderProps { */ border?: BorderShorthand; /** - * Set the width of the border. - * - * If set, it takes precedence over the `border` property's width. - * - * Like CSS, up to 4 values can be specified. - * - * If one value is specified, it applies to all sides. - * - * If two values are specified, they apply to the block sides and inline sides respectively. - * - * If three values are specified, they apply to the block-start, both inline sides, and block-end respectively. - * - * If four values are specified, they apply to the block-start, block-end, inline-start, and inline-end sides respectively. + * Sets the thickness of the border using size keywords. Supports [1-to-4-value syntax](https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand_properties#edges_of_a_box) for specifying different widths per edge. * * @default '' - meaning no override */ borderWidth?: MaybeAllValuesShorthandProperty | ''; /** - * Set the style of the border. - * - * If set, it takes precedence over the `border` property's style. - * - * Like CSS, up to 4 values can be specified. - * - * If one value is specified, it applies to all sides. - * - * If two values are specified, they apply to the block sides and inline sides respectively. - * - * If three values are specified, they apply to the block-start, both inline sides, and block-end respectively. - * - * If four values are specified, they apply to the block-start, block-end, inline-start, and inline-end sides respectively. + * Sets the line style of the border. Controls the visual pattern of the border lines (for example, solid, dashed, dotted). Supports [1-to-4-value syntax](https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand_properties#edges_of_a_box) for specifying different styles per edge. * * @default '' - meaning no override */ borderStyle?: MaybeAllValuesShorthandProperty | ''; /** - * Set the color of the border. - * - * If set, it takes precedence over the `border` property's color. + * Sets the color intensity of the border. Controls how prominent the border appears. * * @default '' - meaning no override */ borderColor?: ColorKeyword | ''; /** - * Set the radius of the border. - * - * [1-to-4-value syntax](https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand_properties#edges_of_a_box) is - * supported. Note that, contrary to the CSS, it uses flow-relative values and the order is: - * - * - 4 values: `start-start start-end end-end end-start` - * - 3 values: `start-start (start-end & end-start) start-end` - * - 2 values: `(start-start & end-end) (start-end & end-start)` - * - * For example: - * - `small-100` means start-start, start-end, end-end and end-start border radii are `small-100`. - * - `small-100 none` means start-start and end-end border radii are `small-100`, start-end and end-start border radii are `none`. - * - `small-100 none large-100` means start-start border radius is `small-100`, start-end border radius is `none`, end-end border radius is `large-100` and end-start border radius is `none`. - * - `small-100 none large-100 small-100` means start-start border radius is `small-100`, start-end border radius is `none`, end-end border radius is `large-100` and end-start border radius is `small-100`. + * Sets the corner rounding radius of the border. Supports [1-to-4-value syntax](https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand_properties#edges_of_a_box) for specifying different radii per corner. * * @defaultValue 'none' */ borderRadius?: MaybeAllValuesShorthandProperty; } +/** + * Properties for controlling overflow behavior when content exceeds container bounds. + */ export interface OverflowProps { /** - * Sets the overflow behavior of the element. + * Controls how the container handles content that exceeds its dimensions: + * - `'visible'`: Content extends beyond the container's boundaries without clipping or scrolling. Overflow content is fully visible and may overlap other elements. This is the default behavior and works well for containers that should expand to fit their content naturally. + * - `'hidden'`: Content that exceeds the container is clipped and hidden from view—users can't see or access the overflow content. No scrollbars appear. Use this for intentionally limiting visible content, creating masked effects, or preventing content from breaking layouts. Be cautious with accessibility—hidden content may include important information users can't access. + * - `'auto'`: Adds scrollbars automatically when content exceeds the container, allowing users to scroll to view overflow content. Scrollbars only appear when needed. Use for scrollable regions, content lists, or any container where users should access all content but space is limited. * - * - `hidden`: clips the content when it is larger than the element’s container. - * The element will not be scrollable and the users will not be able - * to access the clipped content by dragging or using a scroll wheel on a mouse. - * - `visible`: the content that extends beyond the element’s container is visible. + * Setting overflow establishes a new block formatting context, which affects layout behaviors like margin collapsing and positioning. * * @default 'visible' */ overflow?: 'hidden' | 'visible'; } +/** + * Base properties for box-like container elements. + */ export interface BaseBoxProps extends AccessibilityVisibilityProps, BackgroundProps, @@ -1240,400 +1218,396 @@ export interface BaseBoxProps BorderProps, OverflowProps { /** - * The content of the Box. + * The child elements to render within this component. */ children?: ComponentChildren; /** - * A label that describes the purpose or contents of the element. - * When set, it will be announced to users using assistive technologies and will provide them with more context. - * - * Only use this when the element's content is not enough context for users using assistive technologies. + * A label that describes the purpose or contents of the element. Announced to users with assistive technologies such as screen readers to provide context. */ accessibilityLabel?: string; } +/** + * Base properties for box-like container elements with semantic role support. + */ export interface BaseBoxPropsWithRole extends BaseBoxProps, AccessibilityRoleProps {} +/** + * Properties for button-like interactive elements with form-related behavior. + */ export interface ButtonBehaviorProps extends InteractionProps, FocusEventProps { /** - * The behavior of the Button. - * - * - `submit`: Used to indicate the component acts as a submit button, meaning it submits the closest form. - * - `button`: Used to indicate the component acts as a button, meaning it has no default action. - * - `reset`: Used to indicate the component acts as a reset button, meaning it resets the closest form (returning fields to their default values). - * - * This property is ignored if the component supports `href` or `commandFor`/`command` and one of them is set. + * The semantic meaning of the button action within a form context: + * - `'button'`: A standard button with no default form behavior + * - `'submit'`: Submits the containing form when activated + * - `'reset'`: Resets the containing form to its initial values when activated * * @default 'button' */ type?: 'submit' | 'button' | 'reset'; /** - * Callback when the Button is activated. - * This will be called before the action indicated by `type`. + * A callback function executed when the element is clicked or activated. * - * @see https://developer.mozilla.org/en-US/docs/Web/API/Element/click_event + * Learn more about [click events on MDN](https://developer.mozilla.org/en-US/docs/Web/API/Element/click_event). */ onClick?: (event: Event) => void; /** - * Disables the Button meaning it cannot be clicked or receive focus. + * Whether the field is disabled, preventing any user interaction. * * @default false */ disabled?: boolean; /** - * Replaces content with a loading indicator while a background action is being performed. - * - * This also disables the Button. + * Indicates whether the button action is currently in progress. When `true`, displays a loading spinner or progress indicator and prevents additional clicks to avoid duplicate submissions. The button remains visually enabled but unresponsive to interaction. Set to `true` when starting an async operation (for example, API call, navigation) and back to `false` when the operation completes or fails. This provides user feedback during long-running operations and prevents race conditions from multiple rapid clicks. * * @default false */ loading?: boolean; } +/** + * Properties for link-like interactive elements with navigation behavior. + */ export interface LinkBehaviorProps extends InteractionProps, FocusEventProps { /** - * The URL to link to. - * - * - If set, it will navigate to the location specified by `href` after executing the `click` event. - * - If a `commandFor` is set, the `command` will be executed instead of the navigation. + * The URL to navigate to when the element is clicked or activated. Supports absolute URLs (for example, `https://shopify.com`), relative URLs (for example, `/products`), and anchor links (for example, `#section-id`). Navigation is triggered after the `onClick` event completes, allowing you to cancel navigation by preventing the default event action. The actual navigation behavior depends on the `target` property—same page, new tab, or external navigation. For security, browsers may block navigation to certain protocols or untrusted origins. Use this to create navigational links, external resource links, or in-app routing. */ href?: string; /** - * Specifies where to display the linked URL. + * Specifies where to display the linked URL: + * - `'auto'`: The target is automatically determined based on the origin of the URL (typically behaves as `'_self'` but surfaces may handle cross-origin URLs differently). + * - `'_blank'`: Opens the URL in a new tab or window. + * - `'_self'`: Opens the URL in the same browsing context. + * - `'_parent'`: Opens the URL in the parent browsing context. + * - `'_top'`: Opens the URL in the topmost browsing context. + * - Custom string: Any other valid target name. * - * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#target - * - * 'auto': The target is automatically determined based on the origin of the URL. + * Learn more about the [`target` attribute on MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#target). * * @implementation Surfaces can set specific rules on how they handle each URL. - * @implementation It’s expected that the behavior of `auto` is as `_self` except in specific cases. + * @implementation It's expected that the behavior of `auto` is as `_self` except in specific cases. * @implementation For example, a surface could decide to open cross-origin URLs in a new window (as `_blank`). * * @default 'auto' */ target?: 'auto' | '_blank' | '_self' | '_parent' | '_top' | AnyString; /** - * Causes the browser to treat the linked URL as a download with the string being the file name. - * Download only works for same-origin URLs or the `blob:` and `data:` schemes. - * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#download + * Treats the link as a file download instead of navigation. When set, clicking the link downloads the resource at the `href` URL rather than navigating to it. The value becomes the suggested filename shown in the download dialog or used by the browser's default save behavior (for example, `download="receipt.pdf"` saves as "receipt.pdf"). If the value is an empty string, the browser determines the filename from the URL or server headers. This only works for same-origin URLs (your app's domain) or `blob:` and `data:` URLs for security reasons—cross-origin URLs will navigate normally. Learn more about the [`download` attribute on MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#download). */ download?: string; /** - * Callback when the link is activated. - * This will be called before navigating to the location specified by `href`. + * A callback function executed when the element is clicked or activated. * - * @see https://developer.mozilla.org/en-US/docs/Web/API/Element/click_event + * Learn more about [click events on MDN](https://developer.mozilla.org/en-US/docs/Web/API/Element/click_event). */ onClick?: (event: Event) => void; } +/** + * Properties for controlling interactions between elements using commands. + */ export interface InteractionProps { /** - * ID of a component that should respond to activations (e.g. clicks) on this component. - * - * See `command` for how to control the behavior of the target. - * - * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#commandfor + * The ID of the target element that should respond when this element is clicked or activated. This creates a relationship where clicking this control (button, clickable) triggers an action on another element in the DOM. The target element must have a matching `id` attribute. Use with the `command` property to specify what action should occur (show, hide, toggle). This enables declarative element control without writing custom click handlers, improving accessibility and reducing JavaScript. Common use cases include: opening modals from buttons, toggling content visibility, showing/hiding sidebars, or controlling overlay states. If both `commandFor` and `onClick` are present, both will execute—the command action occurs first, then the click handler. + * Learn more about [`commandfor` on MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#commandfor). */ commandFor?: string; /** - * Sets the action the `commandFor` should take when this clickable is activated. - * - * See the documentation of particular components for the actions they support. + * The action to perform on the target element specified by `commandFor`: + * - `'--auto'`: Execute the target element's default action (typically show for overlays, or the element's primary interaction). + * - `'--show'`: Make the target element visible by calling its `showOverlay()` method or setting appropriate visibility properties. + * - `'--hide'`: Hide the target element by calling its `hideOverlay()` method or setting appropriate visibility properties. + * - `'--toggle'`: Switch the target element's visibility state—if visible, hide it; if hidden, show it. + * - `'--copy'`: Copy content to the clipboard (requires the target to be a compatible element with copy functionality). * - * - `--auto`: a default action for the target component. - * - `--show`: shows the target component. - * - `--hide`: hides the target component. - * - `--toggle`: toggles the target component. - * - `--copy`: copies the target ClipboardItem. + * The command executes when this element is clicked, before any `onClick` handlers fire. If the target element doesn't support the specified command, the action may fail silently. + * Learn more about [button commands on MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#command). * * @default '--auto' - * - * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#command */ command?: '--auto' | '--show' | '--hide' | '--toggle' | '--copy'; /** - * ID of a component that should respond to interest (e.g. hover and focus) on this component. + * The ID of a target element that should respond to hover and focus events on this element, creating an "interest" relationship. When the user hovers over or focuses this element, the target element receives corresponding interest events, allowing it to preview or prepare content. This is useful for implementing tooltip-like previews, image zoom on hover, showing additional details before clicking, or loading content speculatively when the user shows interest. The target element must have a matching `id` and listen for interest events. Unlike `commandFor` which responds to clicks, this responds to hover and focus, providing earlier user intent signals. */ interestFor?: string; } +/** + * Combined properties for elements that can behave as both buttons and links. + */ export interface BaseClickableProps extends ButtonBehaviorProps, LinkBehaviorProps {} export interface ButtonProps extends GlobalProps, BaseClickableProps { /** - * A label that describes the purpose or contents of the Button. It will be read to users using assistive technologies such as screen readers. - * - * Use this when using only an icon or the Button text is not enough context - * for users using assistive technologies. + * A label that describes the purpose or contents of the element. Announced to users with assistive technologies such as screen readers to provide context. */ accessibilityLabel?: string; /** - * The content of the Button. + * The child elements to render within this component. */ children?: ComponentChildren; /** - * The type of icon to be displayed in the Button. + * The icon identifier specifying which icon to display. Accepts any valid icon name from the icon set. * * @default '' */ icon?: IconType | AnyString; /** - * The displayed inline width of the Button. - * - * - `auto`: the size of the button depends on the surface and context. - * - `fill`: the button will takes up 100% of the available inline size. - * - `fit-content`: the button will take up the minimum inline-size required to fit its content. + * Controls how the element's width adapts to its container and content. * * @default 'auto' */ inlineSize?: 'auto' | 'fill' | 'fit-content'; /** - * Changes the visual appearance of the Button. + * Changes the visual appearance and prominence of the button: + * - `'auto'`: The variant is automatically determined by context + * - `'primary'`: Creates a prominent call-to-action button with high visual emphasis for the most important action on a screen + * - `'secondary'`: Provides a less prominent button appearance for supporting actions and secondary interactions + * - `'tertiary'`: Provides the least prominent button appearance for tertiary or optional actions * - * @default 'auto' - the variant is automatically determined by the Button's context + * @default 'auto' */ variant?: 'auto' | 'primary' | 'secondary' | 'tertiary'; /** - * Sets the tone of the Button based on the intention of the information being conveyed. + * Sets the tone of the button, based on the intention of the action being performed: + * - `'auto'`: Automatically determines the appropriate tone based on context + * - `'neutral'`: The standard tone for general actions and interactions + * - `'caution'`: Indicates actions that require careful consideration + * - `'warning'`: Alerts users to potential issues or important information + * - `'critical'`: Used for destructive actions like deleting or removing content * * @default 'auto' */ tone?: ToneKeyword; /** - * Indicate the text language. Useful when the text is in a different language than the rest of the page. - * It will allow assistive technologies such as screen readers to invoke the correct pronunciation. - * [Reference of values](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry) ("subtag" label) + * Indicates the language of the text content. Useful when text is in a different language than the rest of the page, allowing assistive technologies to invoke correct pronunciation. [Reference of language subtag values](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry). */ lang?: string; } +/** + * Base properties for all form input elements. + */ export interface BaseInputProps { /** - * An identifier for the field that is unique within the nearest containing form. + * An identifier for the field that is unique within the nearest containing form. This name is used as the key when the form data is submitted. If omitted, the field's value won't be included in form submissions. Use meaningful names that describe the data being collected (for example, `"email"`, `"quantity"`, `"customer-note"`). */ name?: string; /** - * Disables the field, disallowing any interaction. + * Whether the field is disabled, preventing any user interaction. When `true`, the field can't receive focus, be edited, or be interacted with. Disabled fields are visually dimmed, excluded from form submission, and announced as disabled to screen readers. Use when a field is temporarily unavailable due to application state, permissions, or dependencies on other fields. * * @default false */ disabled?: boolean; } +/** + * Properties for controlled form input elements with value and change callbacks. + */ export interface InputProps extends BaseInputProps { /** - * Callback when the user has **finished editing** a field, e.g. once they have blurred the field. - * - * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event + * A callback function executed when the user has committed a value change, typically triggered when the field loses focus (blur) after the value has been modified. Unlike `onInput`, this fires only once after editing is complete, not during typing. The event contains the finalized value. Use this for validation, saving data, or triggering actions that should occur after the user finishes editing rather than during typing. For controlled components, update the `value` prop in this callback. This is ideal for expensive operations like API calls that shouldn't happen on every keystroke. + * Learn more about [change events on MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event). */ onChange?: (event: Event) => void; /** - * Callback when the user makes any changes in the field. - * - * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/input_event + * A callback function executed immediately when the user makes any change to the field value. Fires on every keystroke, paste, or other input modification before the field loses focus. The event contains the current field value. Use this for real-time validation, character counting, formatting input as users type, or implementing autocomplete/search-as-you-type features. For controlled components, update the `value` prop in this callback to keep state in sync. Be cautious with expensive operations here as this fires frequently during typing. + * Learn more about [input events on MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/input_event). */ onInput?: (event: Event) => void; /** - * The current value for the field. If omitted, the field will be empty. + * The current value of the field. When provided, this creates a controlled component where this value must be updated in response to user input using `onChange` or `onInput` callbacks. The format and valid values depend on the specific field type. If both `value` and `defaultValue` are provided, `value` takes precedence. */ value?: string; /** - * The default value for the field. + * The default value used when the field is first rendered. Only applies if no `value` prop is provided, creating an uncontrolled component where the browser manages the field state internally. After initial render, the component handles its own state and you can read the current value from the DOM. Use this for forms where you don't need to control every state change but want to set initial values. For controlled components with full state management, use `value` instead. * * @implementation `defaultValue` reflects to the `value` attribute. */ defaultValue?: string; } +/** + * Properties for form inputs that support multiple selections. + */ export interface MultipleInputProps extends BaseInputProps { /** - * Callback when the user has selected option(s). - * - * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event + * A callback function executed when the user has finished editing the field, typically triggered on blur after the value has changed. + * Learn more about [change events on MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event). */ onChange?: (event: Event) => void; /** - * Callback when the user has selected option(s). - * - * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/input_event + * A callback function executed when the user makes any change to the field value. Fires on each keystroke or interaction. + * Learn more about [input events on MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/input_event). */ onInput?: (event: Event) => void; /** - * An array of the `value`s of the selected options. - * - * This is a convenience prop for setting the `selected` prop on child options. + * An array containing the values of currently selected options in a multi-select choice list. When provided, this creates a controlled component where this array must be updated in response to user selections using the `onChange` callback. The array should contain the `value` properties of selected child `Choice` components. For single-select lists (`multiple={false}`), this array should contain zero or one items. For multi-select lists, it can contain multiple items. This is a convenience property that automatically sets the `selected` state on matching child choices based on their `value` properties. When a choice's value appears in this array, it's automatically marked as selected. Update this array immutably in callbacks (create new arrays rather than mutating). */ values?: string[]; } +/** + * Properties for displaying field validation errors. + */ export interface FieldErrorProps { /** - * Indicate an error to the user. The field will be given a specific stylistic treatment - * to communicate problems that have to be resolved immediately. + * An error message to display when the field contains invalid data or fails validation. When set, the field receives error styling (typically a red border and error icon) and the message appears below the field to guide users toward fixing the issue. The error is announced to screen readers for accessibility. Clear the error by setting this to an empty string or `undefined`. Display errors after validation fails, typically on blur or form submission. */ error?: string; } +/** + * Basic properties for form fields including labels, validation requirements, and error states. + */ export interface BasicFieldProps extends FieldErrorProps, LabelAccessibilityVisibilityProps { /** - * Whether the field needs a value. This requirement adds semantic value - * to the field, but it will not cause an error to appear automatically. - * If you want to present an error when this field is empty, you can do - * so with the `error` property. + * Whether the field must have a value before form submission. When `true`, the field is marked as required (typically with an asterisk), announced as required to screen readers, and triggers browser validation on form submit. This property adds semantic meaning but doesn't prevent submission on its own - validation logic must be implemented and the `error` property to display validation messages. * * @default false */ required?: boolean; /** - * Content to use as the field label. + * The text label that describes what information the field is requesting from the user. Labels are always visible (unlike placeholders which disappear on input) and are announced by screen readers, making them critical for accessibility. Labels typically appear above or beside the field and remain visible while the user interacts with the field. Use clear, concise labels that describe the expected input (for example, "Email address", "Quantity", "Customer note"). Required fields should be indicated in the label or use the `required` property for semantic marking. */ label?: string; } +/** + * Properties for adding supplementary help text to form fields. + */ export interface FieldDetailsProps { /** - * Additional text to provide context or guidance for the field. - * This text is displayed along with the field and its label - * to offer more information or instructions to the user. - * - * This will also be exposed to screen reader users. + * Supplementary help text that provides additional context, instructions, or constraints for the field. This text typically appears below the label in a smaller, subdued style and remains visible at all times (unlike placeholders). Screen readers announce this text along with the label to provide complete field context. Use for format requirements (for example, "Use YYYY-MM-DD format"), character limits (for example, "Maximum 500 characters"), helpful hints (for example, "This will be shown on the receipt"), or clarifying instructions (for example, "Leave blank to use default shipping address"). Avoid duplicating information already in the label or placeholder. */ details?: string; } +/** + * Complete properties for standard form fields including value, label, placeholder, validation, and callbacks. + */ export interface FieldProps extends BasicFieldProps, InputProps, FocusEventProps, FieldDetailsProps { /** - * A short hint that describes the expected value of the field. + * A short hint that provides guidance about the expected value or format of the field. Displayed when the field is empty and disappears once the user starts typing. Placeholders should supplement the label, not replace it - always provide a `label` as well since placeholders may not be accessible to all screen readers. Use for format examples (for example, "YYYY-MM-DD"), helpful hints (for example, "Leave blank for default"), or clarifying expected input (for example, "Enter SKU or product name"). */ placeholder?: string; } +/** + * Base properties for text-based input fields including placeholder and read-only state. + */ export interface BaseTextFieldProps extends FieldProps { /** - * The field cannot be edited by the user. It is focusable will be announced by screen readers. + * Indicates whether the field can be edited. When `true`, the field is focusable and announced by screen readers but can't be modified by the user. Unlike `disabled`, read-only fields can still receive focus, be copied, and participate in form submission. Use read-only for data that users need to see and interact with but shouldn't change, such as calculated values or reference information. * * @default false */ readOnly?: boolean; } +/** + * Properties for adding decorative elements like icons, prefixes, suffixes, and accessories to form fields. + */ export interface FieldDecorationProps { /** - * A value to be displayed immediately after the editable portion of the field. - * - * This is useful for displaying an implied part of the value, such as "@shopify.com", or "%". - * - * This cannot be edited by the user, and it isn't included in the value of the field. - * - * It may not be displayed until the user has interacted with the input. - * For example, an inline label may take the place of the suffix until the user focuses the input. + * Static text displayed immediately after the editable portion of the field, typically inside the field border. This text is non-interactive and purely decorative—users can't edit it and it's not included in the field's value when submitted. The suffix remains visible at all times, even when the field is empty. Common uses include domain suffixes (for example, "@shopify.com" for email fields), units of measurement (for example, "kg", "%", "USD"), or clarifying context (for example, "/month" for subscription pricing). Choose between suffix and prefix based on natural reading order for your use case. * * @default '' */ suffix?: string; /** - * A value to be displayed immediately before the editable portion of the field. - * - * This is useful for displaying an implied part of the value, such as "https://" or "+353". - * - * This cannot be edited by the user, and it isn't included in the value of the field. - * - * It may not be displayed until the user has interacted with the input. - * For example, an inline label may take the place of the prefix until the user focuses the input. + * Static text displayed immediately before the editable portion of the field, typically inside the field border. This text is non-interactive and purely decorative—users can't edit it and it's not included in the field's value when submitted. The prefix remains visible at all times, even when the field is empty. Common uses include currency symbols (for example, "$", "€", "£"), protocol indicators (for example, "https://"), measurement prefixes (for example, "#", "@"), or fixed identifiers. The prefix helps users understand the expected format without consuming characters from maxLength limits. * * @default '' */ prefix?: string; /** - * The type of icon to be displayed in the field. + * The icon identifier specifying which icon to display in the field, typically positioned at the start of the field before the input area. The icon is decorative and helps users quickly identify the field's purpose through visual recognition. The icon is announced to screen readers along with the field's accessible name. Use icons that clearly communicate the field's purpose (for example, search icon for search fields, calendar icon for date fields, lock icon for password fields). The icon doesn't affect the field's functionality but improves visual recognition and scannability in forms. Avoid using both icon and prefix simultaneously as this can create visual clutter. * * @default '' */ icon?: IconType | AnyString; /** - * Additional content to be displayed in the field. - * Commonly used to display an icon that activates a tooltip providing more information. + * Additional interactive content displayed within the field, typically positioned at the end of the field after the input area. Only text-only `Button` and `Clickable` components are supported—no icons or complex content. Use the `slot="accessory"` attribute to place elements here. Common uses include action buttons (for example, "Copy" button, "Generate" button, "Clear" button), toggle visibility controls (for example, "Show password" button), or quick actions related to the field (for example, "Paste from clipboard"). The accessory must not interfere with the field's primary input functionality. Ensure sufficient contrast and touch target sizes for mobile usability. */ accessory?: ComponentChildren; } +/** + * Properties for defining numeric value constraints and controls. + */ export interface NumberConstraintsProps { /** - * The highest decimal or integer to be accepted for the field. - * When used with `step` the value will round down to the max number. - * - * Note: a user will still be able to use the keyboard to input a number higher than - * the max. It is up to the developer to add appropriate validation. + * The highest decimal or integer value that the field accepts. When used with `stepper` controls, the increment button becomes disabled at this value and attempting to increment rounds down to max. When users type values using keyboard, they can enter numbers above max—browser validation will flag these as invalid but won't prevent entry, so implement your own validation in `onChange` or before form submission. Use this to enforce business rules like maximum quantities, price caps, or valid ranges. Set to `Infinity` (default) for no upper limit. * * @default Infinity */ max?: number; /** - * The lowest decimal or integer to be accepted for the field. - * When used with `step` the value will round up to the min number. - * - * Note: a user will still be able to use the keyboard to input a number lower than - * the min. It is up to the developer to add appropriate validation. + * The lowest decimal or integer value that the field accepts. When used with `stepper` controls, the decrement button becomes disabled at this value and attempting to decrement rounds up to min. When users type values using keyboard, they can enter numbers below min—browser validation will flag these as invalid but won't prevent entry, so implement your own validation in `onChange` or before form submission. Use this to enforce business rules like minimum quantities, preventing negative values, or valid ranges. Set to `-Infinity` (default) for no lower limit. * * @default -Infinity */ min?: number; /** - * The amount the value can increase or decrease by. This can be an integer or decimal. - * If a `max` or `min` is specified with `step` when increasing/decreasing the value - * via the buttons, the final value will always round to the `max` or `min` - * rather than the closest valid amount. + * The increment/decrement amount for adjusting the numeric value. Determines how much the value changes when users click stepper buttons or press keyboard arrow keys (up/down). For example, `step="0.01"` allows currency precision, `step="5"` for quantities in increments of 5, or `step="0.25"` for quarter-hour time intervals. The browser may also use this for validation, flagging values that aren't valid steps from the `min` value. Decimals are supported unless using `stepper` controls which only accept integers. * * @default 1 */ step?: number; /** - * Sets the type of controls displayed in the field. + * The type of controls displayed for the field: * - * - `stepper`: displays buttons to increase or decrease the value of the field by the stepping interval defined in the `step` property. - * Appropriate mouse and [keyboard interactions](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/spinbutton_role#keyboard_interactions) to control the value of the field are enabled. - * - `none`: no controls are displayed and users must input the value manually. Arrow keys and scroll wheels can’t be used either to avoid accidental changes. - * - `auto`: the presence of the controls depends on the surface and context. + * - `'auto'` - An automatic setting where the presence of controls depends on the surface and context. The system determines the most appropriate control type based on the usage scenario. + * - `'stepper'` - Displays increment (+) and decrement (-) buttons for adjusting the numeric value. When `stepper` controls are enabled, the field behavior is constrained: it accepts only integer values, always contains a value (never empty), and automatically validates against `min` and `max` bounds. The `label`, `details`, `placeholder`, `error`, `required`, and `inputMode` properties aren't supported with `stepper` controls. + * - `'none'` - A control type with no visible controls where users must input the value manually using the keyboard. * * @default 'auto' */ controls?: 'auto' | 'stepper' | 'none'; } +/** + * Properties for defining minimum and maximum character length constraints on text inputs. + */ export interface MinMaxLengthProps { /** - * Specifies the maximum number of characters allowed. + * The maximum number of characters allowed in the text field. The browser prevents users from typing or pasting beyond this limit—additional characters are automatically truncated. The character count includes all characters (letters, numbers, spaces, special characters). This provides immediate feedback by blocking input rather than showing validation errors. Use this for enforcing hard limits like database column sizes, API constraints, or UX requirements. Commonly combined with character counter displays to show remaining space (for example, "45/100 characters"). * * @default Infinity */ maxLength?: number; /** - * Specifies the min number of characters allowed. + * The minimum number of characters required for the field value to be considered valid. Unlike `maxLength`, this doesn't prevent users from entering fewer characters—instead, browser validation marks the field as invalid if the value is too short. Validation typically occurs on form submission or blur. The field can be empty unless also marked `required`. Use this for ensuring sufficient input quality, like minimum password lengths, meaningful descriptions, or codes with fixed lengths. Combine with the `error` property to display user-friendly validation messages. * * @default 0 */ minLength?: number; } +/** + * Base properties for selectable options including value, disabled state, and accessibility labels. + */ export interface BaseSelectableProps { /** - * A label used for users using assistive technologies like screen readers. When set, any children or `label` supplied will not be announced. - * This can also be used to display a control without a visual label, while still providing context to users using screen readers. + * A label that describes the purpose or contents of the element. Announced to users with assistive technologies such as screen readers to provide context. */ accessibilityLabel?: string; /** - * Disables the control, disallowing any interaction. + * Whether the field is disabled, preventing any user interaction. * * @default false */ disabled?: boolean; /** - * The value used in form data when the control is checked. + * The unique value associated with this selectable option. This value is what gets submitted with forms when the option is selected, and is used to identify which options are selected in the parent `ChoiceList`'s `values` array. The value should be unique among siblings within the same choice list to avoid selection ambiguity. When a choice is selected, this value appears in form data and in the parent's `values` array. Use meaningful, stable values that identify the choice semantically (for example, `"small"`, `"express-shipping"`, `"agree-to-terms"`) rather than display text which may change or be localized. The value isn't displayed to users—use the choice's `children` or label for visible text. */ value?: string; } +/** + * Properties for individual options within choice lists, including selection state management. + */ export interface BaseOptionProps extends BaseSelectableProps { /** - * Whether the control is active. + * Whether the choice control is currently active or selected. This creates a controlled component - this value must be updated in response to user interactions using `onChange` handlers. When `true`, the choice appears selected with appropriate visual styling and is included in form submissions. Use this for controlled selection state where you manage the selected state in your application. If both `selected` and `defaultSelected` are provided, `selected` takes precedence. * * @default false */ selected?: boolean; /** - * Whether the control is active by default. + * Indicates whether the control is selected by default when first rendered. This creates an uncontrolled component where the browser manages selection state internally. Use this when you want initial selection state but don't need to control every state change. The component will handle selection internally after the initial render. Prefer `selected` for controlled components where you need full control over selection state. * * @implementation `defaultSelected` reflects to the `selected` attribute. * @@ -1641,9 +1615,12 @@ export interface BaseOptionProps extends BaseSelectableProps { */ defaultSelected?: boolean; } +/** + * Properties for a single choice option including label, details, selection state, and additional content. + */ export interface ChoiceProps extends GlobalProps, BaseOptionProps { /** - * Content to use as the choice label. + * The label content for the choice option. * * @implementation (StringChildren) The label is produced by extracting and * concatenating the text nodes from the provided content; any markup or @@ -1655,64 +1632,57 @@ export interface ChoiceProps extends GlobalProps, BaseOptionProps { */ children?: ComponentChildren | StringChildren; /** - * Additional text to provide context or guidance for the input. - * - * This text is displayed along with the input and its label - * to offer more information or instructions to the user. + * Additional text or content that provides context or guidance for the choice option. Displayed alongside the option label to offer more information or instructions to the user. Also exposed to screen reader users. * * @implementation this content should be linked to the input with an `aria-describedby` attribute. */ details?: ComponentChildren; /** - * Set to `true` to associate a choice with the error passed to `ChoiceList` + * An error state indicator for the choice option. When `true`, the option will be given specific stylistic treatment to communicate validation issues. * * @default false */ error?: boolean; /** - * Secondary content for a choice. + * The additional content displayed alongside the primary choice label. Useful for providing supplementary information or context. */ secondaryContent?: ComponentChildren; /** - * Content to display when the option is selected. - * - * This can be used to provide additional information or options related to the choice. + * The content displayed only when the option is selected. Useful for showing additional details or confirmation information. */ selectedContent?: ComponentChildren; } +/** + * Properties for a list of choice options with support for single or multiple selection modes. + */ export interface ChoiceListProps extends GlobalProps, Pick, MultipleInputProps, FieldDetailsProps { /** - * Whether multiple choices can be selected. + * Whether multiple choices can be selected simultaneously. When `true`, users can select multiple options and the `values` array will contain all selected values. When `false`, only one option can be selected at a time and selecting a new option automatically deselects the previous one. * * @default false */ multiple?: boolean; /** - * The choices a user can select from. - * - * Accepts `Choice` components. + * The child elements to render within this component. */ children?: ComponentChildren; /** - * Disables the field, disallowing any interaction. - * - * `disabled` on any child choices is ignored when this is true. + * Whether the field is disabled, preventing any user interaction. * * @default false */ disabled?: MultipleInputProps['disabled']; /** - * The variant of the choice grid. - * - * - `auto`: The variant is determined by the context. - * - `list`: The choices are displayed in a list. - * - `inline`: The choices are displayed on the inline axis. - * - `block`: The choices are displayed on the block axis. - * - `grid`: The choices are displayed in a grid. + * Controls the visual layout and presentation style of the choice options: + * - `'auto'`: The layout is automatically determined based on context + * - `'list'`: Displays choices in a vertical list format + * - `'inline'`: Displays choices in a horizontal inline format + * - `'block'`: Displays choices as block-level button-like elements + * - `'grid'`: Displays choices in a grid layout * * @implementation The `block`, `inline` and `grid` variants are more suitable for button looking choices, but it's at the * discretion of each surface. @@ -1726,49 +1696,28 @@ export interface ClickableProps BaseBoxProps, BaseClickableProps { /** - * Disables the clickable, and indicates to assistive technology that the loading is in progress. - * - * This also disables the clickable. + * Indicates whether the action is currently in progress. When `true`, typically displays a loading indicator and may disable interaction. */ loading?: BaseClickableProps['loading']; /** - * Disables the clickable, meaning it cannot be clicked or receive focus. - * - * In this state, onClick will not fire. - * If the click event originates from a child element, the event will immediately stop propagating from this element. - * - * However, items within the clickable can still receive focus and be interacted with. - * - * This has no impact on the visual state by default, - * but developers are encouraged to style the clickable accordingly. + * Whether the element is disabled, preventing any user interaction. */ disabled?: BaseClickableProps['disabled']; /** - * Indicate the text language. Useful when the text is in a different language than the rest of the page. - * It will allow assistive technologies such as screen readers to invoke the correct pronunciation. - * [Reference of values](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry) ("subtag" label) + * Specifies the language of text content using an [IETF BCP 47](https://en.wikipedia.org/wiki/IETF_language_tag) language tag (for example, `"en"` for English, `"fr"` for French, `"es-MX"` for Mexican Spanish, `"zh-Hans"` for Simplified Chinese). This enables assistive technologies to use correct pronunciation and language-specific text rendering. * * @default '' */ lang?: string; } +/** + * Properties for enabling browser autocomplete functionality on form fields. + */ export interface AutocompleteProps< AutocompleteField extends AnyAutocompleteField, > { /** - * A hint as to the intended content of the field. - * - * When set to `on` (the default), this property indicates that the field should support - * autofill, but you do not have any more semantic information on the intended - * contents. - * - * When set to `off`, you are indicating that this field contains sensitive - * information, or contents that are never saved, like one-time codes. - * - * Alternatively, you can provide value which describes the - * specific data you would like to be entered into this field during autofill. - * - * @see Learn more about the set of {@link https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#autofill-detail-tokens|autocomplete values} supported in browsers. + * Specifies the type of data expected in the field to enable browser autocomplete functionality. When set to a specific field type (for example, `'email'`, `'name'`, `'address-line1'`), browsers offer suggestions from previously entered or saved information, improving data entry speed and accuracy. Set to `'on'` to enable generic autocomplete without specifying data type. Set to `'off'` to disable autocomplete entirely for sensitive fields (for example, one-time codes, PINs, credit card security codes). The browser respects user preferences and privacy settings, so autocomplete suggestions may not always appear even when enabled. Prefix field types with section identifiers (`section-shipping`) or groups (`billing`, `shipping`) to disambiguate when multiple similar fields exist on the same page. Accepts standard [HTML autocomplete tokens per the WHATWG specification](https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#autofill-detail-tokens). * * @default 'tel' for PhoneField * @default 'email' for EmailField @@ -1784,19 +1733,18 @@ export interface AutocompleteProps< | 'off'; } /** - * The “section” scopes the autocomplete data that should be inserted - * to a specific area of the page. + * A section prefix that scopes the autocomplete data to a specific area of the page. * * Commonly used when there are multiple fields with the same autocomplete needs * in the same page. For example: 2 shipping address forms in the same page. */ export type AutocompleteSection = `section-${string}`; /** - * The contact information group the autocomplete data should be sourced from. + * The contact information category that autocomplete data should be sourced from. */ export type AutocompleteGroup = 'shipping' | 'billing'; /** - * The contact information subgroup the autocomplete data should be sourced from. + * The contact information subcategory that autocomplete data should be sourced from. */ export type AutocompleteAddressGroup = 'fax' | 'home' | 'mobile' | 'pager'; export type AnyAutocompleteField = @@ -1864,6 +1812,9 @@ export type AnyAutocompleteField = | `${AutocompleteAddressGroup} tel-local-suffix` | `${AutocompleteAddressGroup} tel-local` | `${AutocompleteAddressGroup} tel-national`; +/** + * Autocomplete field types applicable to text input fields. + */ export type TextAutocompleteField = ExtractStrict< AnyAutocompleteField, | 'additional-name' @@ -1897,12 +1848,15 @@ export type TextAutocompleteField = ExtractStrict< | 'cc-family-name' | 'cc-type' >; +/** + * Properties for an interactive date picker component with single, multiple, or range selection modes. + */ export interface DatePickerProps extends GlobalProps, InputProps, FocusEventProps { /** - * Default month to display in `YYYY-MM` format. + * The default month to display in `YYYY-MM` format when the picker is first shown. * * This value is used until `view` is set, either directly or as a result of user interaction. * @@ -1910,74 +1864,35 @@ export interface DatePickerProps */ defaultView?: string; /** - * Displayed month in `YYYY-MM` format. - * - * `onViewChange` is called when this value changes. - * - * Defaults to `defaultView`. + * The currently displayed month in `YYYY-MM` format. Controls which month is visible in the date picker. */ view?: string; /** - * Called whenever the month to display changes. - * - * @param view The new month to display in `YYYY-MM` format. + * A callback function executed when the visible month displayed in the date picker changes, either through user navigation (clicking next/previous month buttons) or programmatic updates to the `view` property. The callback receives the new month as a string in `YYYY-MM` format (for example, `"2024-05"`). Use this to track which month users are viewing, load month-specific data (like availability or pricing), sync the view with external state, or implement custom navigation controls. For controlled date pickers, update the `view` property in this callback to keep the displayed month in sync with your application state. The callback fires after the month has changed but before the new month's dates are fully rendered, making it ideal for triggering data fetches. */ onViewChange?: (view: string) => void; /** - * The type of selection the date picker allows. - * - * - `single` allows selecting a single date. - * - `multiple` allows selecting multiple non-contiguous dates. - * - `range` allows selecting a single range of dates. + * Controls the selection mode of the date picker: + * - `'single'`: Allows selecting one date + * - `'multiple'`: Allows selecting multiple individual dates + * - `'range'`: Allows selecting a continuous range of dates * * @default "single" */ type?: 'single' | 'multiple' | 'range'; /** - * Dates that can be selected. - * - * A comma-separated list of dates, date ranges. Whitespace is allowed after commas. - * - * The default `''` allows all dates. - * - * - Dates in `YYYY-MM-DD` format allow a single date. - * - Dates in `YYYY-MM` format allow a whole month. - * - Dates in `YYYY` format allow a whole year. - * - Ranges are expressed as `start--end`. - * - Ranges are inclusive. - * - If either `start` or `end` is omitted, the range is unbounded in that direction. - * - If parts of the date are omitted for `start`, they are assumed to be the minimum possible value. - * So `2024--` is equivalent to `2024-01-01--`. - * - If parts of the date are omitted for `end`, they are assumed to be the maximum possible value. - * So `--2024` is equivalent to `--2024-12-31`. - * - Whitespace is allowed either side of `--`. + * Specifies allowed date values or ranges for selection. Uses ISO date format (YYYY-MM-DD) or partial dates (YYYY-MM, YYYY). Supports range syntax with `--` separator and comma-separated values. * * @default "" * * @example * `2024-02--2025` // allow any date from February 2024 to the end of 2025 - * `2024-02--` // allow any date from February 2024 to the end of the month + * `2024-02--` // allow any date from February 2024 onwards * `2024-05-09, 2024-05-11` // allow only the 9th and 11th of May 2024 */ allow?: string; /** - * Dates that cannot be selected. These subtract from `allow`. - * - * A comma-separated list of dates, date ranges. Whitespace is allowed after commas. - * - * The default `''` has no effect on `allow`. - * - * - Dates in `YYYY-MM-DD` format disallow a single date. - * - Dates in `YYYY-MM` format disallow a whole month. - * - Dates in `YYYY` format disallow a whole year. - * - Ranges are expressed as `start--end`. - * - Ranges are inclusive. - * - If either `start` or `end` is omitted, the range is unbounded in that direction. - * - If parts of the date are omitted for `start`, they are assumed to be the minimum possible value. - * So `2024--` is equivalent to `2024-01-01--`. - * - If parts of the date are omitted for `end`, they are assumed to be the maximum possible value. - * So `--2024` is equivalent to `--2024-12-31`. - * - Whitespace is allowed either side of `--`. + * Specifies disallowed date values or ranges that can't be selected. Uses ISO date format (YYYY-MM-DD) or partial dates (YYYY-MM, YYYY). Supports range syntax with `--` separator and comma-separated values. Takes precedence over `allow`. * * @default "" * @@ -1987,82 +1902,49 @@ export interface DatePickerProps */ disallow?: string; /** - * Days of the week that can be selected. These intersect with the result of `allow` and `disallow`. - * - * A comma-separated list of days. Whitespace is allowed after commas. - * - * The default `''` has no effect on the result of `allow` and `disallow`. - * - * Days are `sunday`, `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday`. + * Specifies which days of the week can be selected. Accepts comma-separated day names (case-insensitive). Further restricts dates within the result of `allow` and `disallow`. * * @default "" * * @example - * 'saturday, sunday' // allow only weekends within the result of `allow` and `disallow`. + * 'saturday, sunday' // allow only weekends + * 'monday, wednesday, friday' // allow only specific weekdays */ allowDays?: string; /** - * Days of the week that cannot be selected. This subtracts from `allowDays`, and intersects with the result of `allow` and `disallow`. - * - * A comma-separated list of days. Whitespace is allowed after commas. - * - * The default `''` has no effect on `allowDays`. - * - * Days are `sunday`, `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday`. + * Specifies which days of the week can't be selected. Accepts comma-separated day names (case-insensitive). Further restricts dates within the result of `allow` and `disallow`. * * @default "" * * @example - * 'saturday, sunday' // disallow weekends within the result of `allow` and `disallow`. + * 'saturday, sunday' // disallow weekends + * 'monday' // disallow Mondays */ disallowDays?: string; /** - * Default selected value. - * - * The default means no date is selected. - * - * If the provided value is invalid, no date is selected. - * - * - If `type="single"`, this is a date in `YYYY-MM-DD` format. - * - If `type="multiple"`, this is a comma-separated list of dates in `YYYY-MM-DD` format. - * - If `type="range"`, this is a range in `YYYY-MM-DD--YYYY-MM-DD` format. The range is inclusive. + * The default date value used when the field is first rendered, in ISO date format (YYYY-MM-DD, for example, `"2024-05-15"`). An empty string means no default date. For date ranges, use comma-separated dates. Only applies if no `value` prop is provided. * * @default "" */ defaultValue?: string; /** - * Current selected value. - * - * The default means no date is selected. - * - * If the provided value is invalid, no date is selected. - * - * Otherwise: - * - * - If `type="single"`, this is a date in `YYYY-MM-DD` format. - * - If `type="multiple"`, this is a comma-separated list of dates in `YYYY-MM-DD` format. - * - If `type="range"`, this is a range in `YYYY-MM-DD--YYYY-MM-DD` format. The range is inclusive. + * The currently selected date value in ISO date format (YYYY-MM-DD, for example, `"2024-05-15"`). An empty string means no date is selected. For date ranges, use comma-separated dates (for example, `"2024-05-15,2024-05-20"`). * * @default "" */ value?: string; /** - * Callback when any date is selected. - * - * - If `type="single"`, fires when a date is selected and happens before `onChange`. - * - If `type="multiple"`, fires when a date is selected before `onChange`. - * - If `type="range"`, fires when a first date is selected (with the partial value formatted as `YYYY-MM-DD--`), and when the last date is selected before `onChange`. + * A callback function executed when the user makes any change to the field value. Fires on each keystroke or interaction. */ onInput?: (event: Event) => void; /** - * Callback when the value is committed. - * - * - If `type="single"`, fires when a date is selected after `onInput`. - * - If `type="multiple"`, fires when a date is selected after `onInput`. - * - If `type="range"`, fires when a range is completed by selecting the end date after `onInput`. + * A callback function executed when the user has finished editing the field, typically triggered on blur after the value has changed. */ onChange?: (event: Event) => void; } +/** + * Properties for a text-based date input field with validation and autocomplete support. + */ export interface DateFieldProps extends GlobalProps, BaseTextFieldProps, @@ -2080,19 +1962,7 @@ export interface DateFieldProps >, AutocompleteProps { /** - * Callback when the field has an invalid date. - * This callback will be called, if the date typed is invalid or disabled. - * - * Dates that don’t exist or have formatting errors are considered invalid. Some examples of invalid dates are: - * - 2021-02-31: February doesn’t have 31 days - * - 2021-02-00: The day can’t be 00 - * - * Disallowed dates are considered invalid. - * - * It’s important to note that this callback will be called only when the user **finishes editing** the date, - * and it’s called right after the `onChange` callback. - * The field is **not** validated on every change to the input. Once the buyer has signalled that - * they have finished editing the field (typically, by blurring the field), the field gets validated and the callback is run if the value is invalid. + * A callback function executed when the user enters an invalid value. Fires after change validation fails. */ onInvalid?: (event: Event) => void; } @@ -2106,6 +1976,9 @@ export type DateAutocompleteField = ExtractStrict< | 'cc-expiry-month' | 'cc-expiry-year' >; +/** + * Properties for a spinner-style date selector with increment/decrement controls. + */ export interface DateSpinnerProps extends GlobalProps, Pick< @@ -2113,102 +1986,116 @@ export interface DateSpinnerProps 'defaultValue' | 'value' | 'onInput' | 'onChange' | 'onBlur' | 'onFocus' > { /** - * Default selected value for the spinner. - * - * This uses a date in `YYYY-MM-DD` format. + * The default date value used when the field is first rendered, in ISO date format (YYYY-MM-DD, for example, `"2024-05-15"`). An empty string means no default date. Only applies if no `value` prop is provided. * * @default "" */ defaultValue?: string; /** - * Current selected value for the spinner. - * - * This uses a date in `YYYY-MM-DD` format. + * The currently selected date value in ISO date format (YYYY-MM-DD, for example, `"2024-05-15"`). An empty string means no date is selected. * * @default "" */ value?: string; /** - * Callback after the wheels have finished spinning and the value has - * settled. - * - * Fires once when inertial/momentum scrolling stops and the selection snaps - * into place. + * A callback function executed when the user makes any change to the field value. Fires on each keystroke or interaction. */ onInput?: (event: Event) => void; /** - * Callback when the selection has been confirmed by the user. - * - * Fires only when the user explicitly commits the selection (for example, by - * pressing a confirmation control). + * A callback function executed when the user has finished editing the field, typically triggered on blur after the value has changed. */ onChange?: (event: Event) => void; } +/** + * Properties for a visual divider line that separates content sections. + */ export interface DividerProps extends GlobalProps { /** - * Specify the direction of the divider. This uses [logical properties](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_logical_properties_and_values). + * The direction of the divider using [logical properties](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_logical_properties_and_values). An inline divider runs horizontally across the content flow, while a block divider runs vertically along the content flow. + * + * Available options: + * - `'inline'`: A horizontal divider that runs perpendicular to the text direction, creating separation between vertically stacked content sections. + * - `'block'`: A vertical divider that runs parallel to the text direction, creating separation between horizontally arranged content sections. * * @default 'inline' */ direction?: 'inline' | 'block'; /** - * Modify the color to be more or less intense. + * The color intensity of the divider. Controls how prominent or subtle the divider appears. * * @default 'base' */ color?: ColorKeyword; } +/** + * Properties for an email address input field with validation and autocomplete support. + */ export interface EmailFieldProps extends GlobalProps, BaseTextFieldProps, MinMaxLengthProps, AutocompleteProps {} +/** + * Autocomplete field types applicable to email input fields. + */ export type EmailAutocompleteField = ExtractStrict< AnyAutocompleteField, 'email' | `${AutocompleteAddressGroup} email` >; +/** + * A spacing size keyword including the option for no spacing. + */ export type SpacingKeyword = SizeKeyword | 'none'; +/** + * Properties for controlling the spacing between child elements in a container. + */ export interface GapProps { /** - * Adjust spacing between elements. - * - * A single value applies to both axes. - * A pair of values (eg `large-100 large-500`) can be used to set the inline and block axes respectively. + * The spacing between child elements. A single value applies to both axes. Two values (for example, `large-100 large-500`) set the block axis (first value) and inline axis (second value) respectively. * * @default 'none' */ gap?: MaybeResponsive>; /** - * Adjust spacing between elements in the block axis. - * - * This overrides the row value of `gap`. + * The spacing between child elements along the block axis (typically vertical). Overrides the block axis value from `gap`. * * @default '' - meaning no override */ rowGap?: MaybeResponsive; /** - * Adjust spacing between elements in the inline axis. - * - * This overrides the column value of `gap`. + * The spacing between child elements along the inline axis (typically horizontal). Overrides the inline axis value from `gap`. * * @default '' - meaning no override */ columnGap?: MaybeResponsive; } +/** + * A baseline alignment position keyword. + */ export type BaselinePosition = 'baseline' | 'first baseline' | 'last baseline'; +/** + * A content distribution strategy keyword for spacing. + */ export type ContentDistribution = | 'space-between' | 'space-around' | 'space-evenly' | 'stretch'; +/** + * A content position alignment keyword. + */ export type ContentPosition = 'center' | 'start' | 'end'; +/** + * A content position with optional overflow safety modifier. + */ export type OverflowPosition = | `unsafe ${ContentPosition}` | `safe ${ContentPosition}`; /** - * Align items sets the align-self value on all direct children as a group. + * A type that defines how children are aligned along the cross axis. + * Sets the align-self value on all direct children as a group. * - * @see https://developer.mozilla.org/en-US/docs/Web/CSS/align-items + * Learn more about [`align-items` on MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/align-items). */ export type AlignItemsKeyword = | 'normal' @@ -2217,9 +2104,9 @@ export type AlignItemsKeyword = | OverflowPosition | ContentPosition; /** - * Justify content defines how the browser distributes space between and around content items along the main-axis of a flex container, and the inline axis of a grid container. + * A type that defines how the browser distributes space between and around content items along the main-axis of a flex container, and the inline axis of a grid container. * - * @see https://developer.mozilla.org/en-US/docs/Web/CSS/justify-content + * Learn more about [`justify-content` on MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/justify-content). */ export type JustifyContentKeyword = | 'normal' @@ -2227,9 +2114,9 @@ export type JustifyContentKeyword = | OverflowPosition | ContentPosition; /** - *Align content sets the distribution of space between and around content items along a flexbox's cross axis, or a grid or block-level element's block axis. + * A type that defines the distribution of space between and around content items along a flexbox's cross axis, or a grid or block-level element's block axis. * - * @see https://developer.mozilla.org/en-US/docs/Web/CSS/align-content + * Learn more about [`align-content` on MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/align-content). */ export type AlignContentKeyword = | 'normal' @@ -2237,90 +2124,90 @@ export type AlignContentKeyword = | ContentDistribution | OverflowPosition | ContentPosition; +/** + * Base properties for text styling and appearance. + */ export interface BaseTypographyProps { /** - * Modify the color to be more or less intense. + * The color intensity of the text. Controls how prominent or subtle the text appears within the interface. * * @default 'base' */ color?: ColorKeyword; /** - * Sets the tone of the component, based on the intention of the information being conveyed. + * The semantic tone of the text, based on the intention of the information being conveyed. Affects color and styling to communicate meaning. * * @default 'auto' */ tone?: ToneKeyword; /** - * Set the numeric properties of the font. + * Controls how numbers are displayed in the text: + * - `'auto'`: Inherits the setting from the parent element. + * - `'normal'`: Uses the default number rendering for the font. + * - `'tabular-nums'`: Uses fixed-width numbers for better alignment in tables and lists. * - * @see https://developer.mozilla.org/en-US/docs/Web/CSS/font-variant-numeric + * Learn more about [`font-variant-numeric` on MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/font-variant-numeric). * - * @default 'auto' - inherit from the parent element + * @default 'auto' */ fontVariantNumeric?: 'auto' | 'normal' | 'tabular-nums'; /** - * Indicate the text language. Useful when the text is in a different language than the rest of the page. - * It will allow assistive technologies such as screen readers to invoke the correct pronunciation. - * [Reference of values](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry) ("subtag" label) - * - * It is recommended to combine it with the `dir` attribute to ensure the text is rendered correctly if the surrounding content’s direction is different. + * Specifies the language of text content using an [IETF BCP 47](https://en.wikipedia.org/wiki/IETF_language_tag) language tag (for example, `"en"` for English, `"fr"` for French, `"es-MX"` for Mexican Spanish, `"zh-Hans"` for Simplified Chinese). This enables assistive technologies to use correct pronunciation and language-specific text rendering. * * @default '' */ lang?: string; /** - * Indicates the directionality of the element’s text. + * Indicates the directionality of the element's text: + * - `ltr`: languages written from left to right (for example, English). + * - `rtl`: languages written from right to left (for example, Arabic). + * - `auto`: the user agent determines the direction based on the content. + * - `''`: direction is inherited from parent elements (equivalent to not setting the attribute). * - * - `ltr`: languages written from left to right (e.g. English) - * - `rtl`: languages written from right to left (e.g. Arabic) - * - `auto`: the user agent determines the direction based on the content - * - `''`: direction is inherited from parent elements (equivalent to not setting the attribute) - * - * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/dir + * Learn more about the [`dir` attribute on MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/dir). * * @default '' */ dir?: 'ltr' | 'rtl' | 'auto' | ''; } +/** + * Properties for controlling multi-line text behavior and truncation. + */ export interface BlockTypographyProps { /** - * Truncates the text content to the specified number of lines. - * - * @see https://developer.mozilla.org/en-US/docs/Web/CSS/-webkit-line-clamp + * Limits the text content to a specified number of visible lines. When text exceeds this limit, it's truncated and an ellipsis (`…`) appears at the end of the last visible line to indicate more content exists. The truncation happens automatically based on the container's width, font size, and line height—narrow containers or large fonts will show fewer words per line. For example, `lineClamp={3}` allows maximum three lines of text regardless of total content length. Users can't access the hidden text unless an expansion mechanism (like a "Read more" button) or tooltip is provided. Commonly applied to maintain consistent layout heights in cards, lists, or grids where varying text lengths would disrupt visual alignment. Common values include 1-2 for titles/labels, 2-3 for descriptions, and 4-6 for preview text. The actual text content remains in the DOM and is accessible to screen readers (full text is announced), search engines, and selection—only the visual display is truncated. Learn more about [`line-clamp` on MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/-webkit-line-clamp). * * @default Infinity - no truncation is applied */ lineClamp?: number; } +/** + * Properties for heading text elements with semantic structure and line clamping. + */ export interface HeadingProps extends GlobalProps, AccessibilityVisibilityProps, BlockTypographyProps { /** - * The content of the Heading. + * The child elements to render within this component. */ children?: ComponentChildren; /** - * Sets the semantic meaning of the component’s content. When set, - * the role will be used by assistive technologies to help users - * navigate the page. - * - * - `heading`: defines the element as a heading to a page or section. - * - `presentation`: the heading level will be stripped, - * and will prevent the element’s implicit ARIA semantics from - * being exposed to the accessibility tree. - * - `none`: a synonym for the `presentation` role. + * Sets the semantic role for assistive technologies. Helps screen reader users navigate and understand page structure. * * @default 'heading' * * @implementation The `heading` role doesn't need to be applied if * the host applies it for you; for example, an HTML host rendering - * an `

` element should not apply the `heading` role. + * an `

` element shouldn't apply the `heading` role. */ accessibilityRole?: | 'heading' | ExtractStrict; } +/** + * Properties for icon elements including type, size, color, and tone. + */ export interface IconProps extends GlobalProps, Pick { @@ -2331,182 +2218,162 @@ export interface IconProps */ tone?: ToneKeyword; /** - * Modify the color to be more or less intense. + * Modify the color to be more or less intense. Use `'subdued'` for secondary icons, `'base'` for standard visibility, or `'strong'` for emphasized icons that need to stand out. * * @default 'base' */ color?: ColorKeyword; /** - * Adjusts the size of the icon. + * Adjusts the size of the icon. Available sizes range from `'small-500'` (smallest) through `'base'` (default) to `'large-500'` (largest), allowing you to match icon size to your interface hierarchy. * * @default 'base' */ size?: SizeKeyword; + /** + * The type of icon to display. + */ type?: IconType | AnyString; } +/** + * Base properties for image elements including source URLs and alternative text. + */ export interface BaseImageProps { /** - * An alternative text description that describe the image for the reader to - * understand what it is about. It is extremely useful for both users using - * assistive technology and sighted users. A well written description - * provides people with visual impairments the ability to participate in - * consuming non-text content. When a screen readers encounters an `s-image`, - * the description is read and announced aloud. If an image fails to load, - * potentially due to a poor connection, the `alt` is displayed on - * screen instead. This has the benefit of letting a sighted buyer know an - * image was meant to load here, but as an alternative, they’re still able to - * consume the text content. Read - * [considerations when writing alternative text](https://www.shopify.com/ca/blog/image-alt-text#4) - * to learn more. + * Alternative text that describes the image content for users who can't see the image. This text is announced by screen readers, displayed when images fail to load or are blocked, and used by search engines for image indexing. Write concise, descriptive alt text that conveys the image's purpose and content (for example, "Product photo of blue running shoes" not "image" or "photo"). For decorative images that don't convey information, use an empty string (`alt=""`) to hide them from screen readers. For images containing text, include that text in the alt description. For complex images like charts or diagrams, consider providing a longer description elsewhere and summarizing in alt text. Alt text is required for accessibility compliance and should describe what users would miss if they couldn't see the image. * * @default `''` - * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#alt + * Learn more about [`alt` on MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#alt). */ alt?: string; /** - * A set of media conditions and their corresponding sizes. + * Defines the image sizes for different viewport widths to help the browser select the optimal image from `srcSet`. This is a comma-separated list of media conditions and corresponding sizes (for example, `"(max-width: 600px) 480px, 800px"`). The browser uses this with `srcSet` to determine which image variant to download based on the device's screen size and pixel density, improving performance by loading appropriately-sized images. For example, mobile devices receive smaller images while desktops get larger, higher-resolution versions. When `srcSet` provides multiple image sizes, `sizes` tells the browser the rendered size at different viewport widths. If omitted, the browser assumes `100vw` (full viewport width). This only affects which image is selected, not how it's displayed—use CSS or `inlineSize` for display sizing. * - * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#sizes + * Learn more about [`sizes` on MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#sizes). */ sizes?: string; /** - * The image source (either a remote URL or a local file resource). - * - * When the image is loading or no `src` is provided, a placeholder will be rendered. - * - * @implementation Surfaces may choose the style of the placeholder, but the space the image occupies should be - * reserved, except in cases where the image area does not have a contextual inline or block size, which should be rare. - * - * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#src + * The image source URL (remote URL or local file resource). When loading or no src is provided, a placeholder is rendered. Ensure URLs are properly formatted and properly formatted. */ src?: string; /** - * A set of image sources and their width or pixel density descriptors. + * A set of image source URLs with descriptors for responsive image selection. Provides multiple image variants at different widths or pixel densities, allowing browsers to choose the most appropriate image for the user's device and screen. Format: comma-separated list of `URL descriptor` pairs where descriptors are either width (`w`) or pixel density (`x`). For example: `"small.jpg 480w, medium.jpg 800w, large.jpg 1200w"` for different widths, or `"standard.jpg 1x, retina.jpg 2x"` for different pixel densities. The browser considers the device's screen size, resolution, network speed, and user preferences when selecting which image to download. This improves performance (smaller images on mobile) and quality (high-DPI images on retina displays). When used with `sizes`, enables fully responsive images. The `src` property serves as fallback for browsers that don't support `srcSet`. * - * This overrides the `src` property. - * - * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#srcset + * Learn more about [`src` on MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#src).set */ srcSet?: string; } +/** + * Properties for image elements including size, aspect ratio, loading behavior, and border styling. + */ export interface ImageProps extends GlobalProps, BaseImageProps, BorderProps { /** - * Sets the semantic meaning of the component’s content. When set, - * the role will be used by assistive technologies to help users - * navigate the page. + * Sets the semantic role for assistive technologies. Helps screen reader users navigate and understand page structure. * * @default 'img' * * @implementation The `img` role doesn't need to be applied if * the host applies it for you; for example, an HTML host rendering - * an `` element should not apply the `img` role. + * an `` element shouldn't apply the `img` role. */ accessibilityRole?: | 'img' | ExtractStrict; /** - * The displayed inline width of the image. + * Controls the displayed width of the image. Choose based on your layout requirements. For mobile interfaces, consider using `'fill'` with defined container dimensions to ensure consistent image display, as dynamic container heights can cause layout inconsistencies in scrollable views. * - * - `fill`: the image will takes up 100% of the available inline size. - * - `auto`: the image will be displayed at its natural size. + * - `'auto'` - Displays the image at its natural size. The image will not render until it has loaded, and the aspect ratio will be ignored. Use for images where maintaining original dimensions is important. + * - `'fill'` - Makes the image take up 100% of the available inline size. The aspect ratio will be respected and the image will take the necessary space. Use for responsive layouts and flexible image containers. * * @default 'fill' - * - * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#width */ inlineSize?: 'fill' | 'auto'; /** - * The aspect ratio of the image. + * The aspect ratio of the image, expressed as width divided by height. * * The rendering of the image will depend on the `inlineSize` value: * - * - `inlineSize="fill"`: the aspect ratio will be respected and the image will take the necessary space. - * - `inlineSize="auto"`: the image will not render until it has loaded and the aspect ratio will be ignored. + * - `inlineSize="fill"`: The aspect ratio will be respected and the image will take the necessary space. + * - `inlineSize="auto"`: The image won't render until it has loaded and the aspect ratio will be ignored. * * For example, if the value is set as `50 / 100`, the getter returns `50 / 100`. * If the value is set as `0.5`, the getter returns `0.5 / 1`. * * @default '1/1' - * - * @see https://developer.mozilla.org/en-US/docs/Web/CSS/aspect-ratio */ aspectRatio?: | `${number}${optionalSpace}/${optionalSpace}${number}` | `${number}`; /** - * Determines how the content of the image is resized to fit its container. - * The image is positioned in the center of the container. + * Controls how the image content is resized within its container. * - * @default 'contain' + * - `'contain'` - Scales the image to fit within the container while maintaining aspect ratio. The entire image will be visible, but there may be empty space. Use when showing the complete image is important. + * - `'cover'` - Scales the image to fill the entire container while maintaining aspect ratio. Parts of the image may be cropped. Use when filling the container completely is more important than showing the entire image. * - * @see https://developer.mozilla.org/en-US/docs/Web/CSS/object-fit + * @default 'contain' */ objectFit?: 'contain' | 'cover'; /** - * Determines the loading behavior of the image: - * - `eager`: Immediately loads the image, irrespective of its position within the visible viewport. - * - `lazy`: Delays loading the image until it approaches a specified distance from the viewport. + * Controls when the browser should begin loading the image resource: + * - `'eager'`: Loads the image immediately when the page loads, regardless of whether it's visible in the viewport. The image downloads in parallel with other page resources. Use for above-the-fold images, critical product photos, or images that will definitely be viewed. This ensures images are ready when needed but increases initial page load bandwidth. + * - `'lazy'`: Defers image loading until the image is approaching the viewport (typically a few hundred pixels before becoming visible). The browser only downloads the image when the user is likely to see it soon. Use for below-the-fold images, gallery images, or images in scrollable lists. This improves initial page load performance and saves bandwidth for images users may never scroll to. The browser maintains a buffer distance so images load before users reach them, preventing visible loading delays. + * + * Lazy loading is most effective for pages with many images, long scrollable content, or mobile users on limited bandwidth. Modern browsers support native lazy loading—older browsers ignore this and load eagerly. * * @default 'eager' - * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#loading + * Learn more about [`loading` on MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#loading). */ loading?: 'eager' | 'lazy'; /** - * Invoked when load completes successfully. + * A callback function executed when the image finishes loading successfully and is ready to display. This fires after the browser has downloaded the image data and decoded it, but may fire before the image is actually painted to the screen. Use this for hiding loading indicators, triggering dependent actions that require the image (like image processing), tracking image load metrics, or executing layout operations that depend on image dimensions. For performance tracking, compare timestamps between navigation start and this callback. Note that cached images may trigger this callback synchronously (immediately), so handle both async and sync invocation in your code. This won't fire if the image fails to load—listen to `onError` for failures. * - * @see https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers/onload + * Learn more about [`onload` on MDN](https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers/onload). */ onLoad?: (event: Event) => void; /** - * Invoked on load error. + * A callback function executed when the image fails to load due to network errors, invalid URLs, unsupported formats, [CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing) issues, or server errors (for example, 404, 500). The event contains limited error details for security reasons—the browser console provides specific failure reasons. Common operations include displaying fallback images (`event.target.src = 'fallback.jpg'`), showing error messages to users, logging failures for monitoring, hiding broken image icons, or providing alternative content when images are unavailable. A common pattern involves attempting to load a fallback image, and if that fails too, hiding the image container entirely. For critical images like product photos, a placeholder SVG or icon may be shown instead of a broken image indicator. This callback doesn't fire for images that are blocked by browser content policies or ad blockers. * - * @see https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers/onerror + * Learn more about [`onerror` on MDN](https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers/onerror). */ onError?: (event: Event) => void; } +/** + * Properties for modal overlay dialogs including size, padding, actions, and lifecycle callbacks. + */ export interface ModalProps extends GlobalProps, BaseOverlayProps, BaseOverlayMethods, ActionSlots { /** - * A label that describes the purpose of the modal. When set, - * it will be announced to users using assistive technologies and will - * provide them with more context. - * - * This overrides the `heading` prop for screen readers. + * A label that describes the purpose or contents of the element. Announced to users with assistive technologies such as screen readers to provide context. */ accessibilityLabel?: string; /** - * A title that describes the content of the Modal. - * + * The title text displayed in the modal header. If omitted and no actions are provided, the modal will be rendered without a header. */ heading?: string; /** - * Adjust the padding around the Modal content. - * - * `base`: applies padding that is appropriate for the element. - * - * `none`: removes all padding from the element. This can be useful when elements inside the Modal need to span - * to the edge of the Modal. For example, a full-width image. In this case, rely on `Box` with a padding of 'base' - * to bring back the desired padding for the rest of the content. + * The padding applied to all edges of the modal content. * * @default 'base' */ padding?: 'base' | 'none'; /** - * Adjust the size of the Modal. - * - * `max`: expands the Modal to its maximum size as defined by the host application, on both the horizontal and vertical axes. + * Controls the display size of the modal: + * - Size keywords (for example, `'small'`, `'base'`, `'large'`): Fixed size options. + * - `'max'`: Modal expands to fill the maximum available space. * * @default 'base' */ size?: SizeKeyword | 'max'; /** - * The content of the Modal. + * The child elements to render within this component. */ children?: ComponentChildren; } +/** + * Properties for numeric input fields with validation, constraints, and optional stepper controls. + */ export interface NumberFieldProps extends GlobalProps, BaseTextFieldProps, @@ -2514,64 +2381,71 @@ export interface NumberFieldProps NumberConstraintsProps, FieldDecorationProps { /** - * Sets the virtual keyboard. + * The virtual keyboard layout that the field displays for numeric input. This property isn't supported when using `stepper` controls. + * + * - `'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. * - * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/inputmode * @default 'decimal' */ inputMode?: 'decimal' | 'numeric'; } +/** + * Autocomplete field types applicable to number input fields. + */ export type NumberAutocompleteField = ExtractStrict< AnyAutocompleteField, 'one-time-code' | 'cc-number' | 'cc-csc' >; +/** + * Properties for page-level layouts including header, breadcrumbs, actions, and sidebar content. + */ export interface PageProps extends GlobalProps, ActionSlots { /** - * The content of the Page. + * The child elements to render within this component. */ children?: ComponentChildren; /** - * The main page heading + * The title text displayed in the page header. If omitted and no actions are provided, the page will be rendered without a header. */ heading?: string; /** - * The text to be used as subtitle. + * A secondary page heading displayed under the main heading in the action bar. */ subheading?: string; /** - * Additional contextual information about the page. + * The additional content displayed in the header area. Commonly used to display clickable text or action elements. Only `Button` and `Clickable` components with text content only are supported in this slot. Use the `slot="accessory"` attribute to place elements in this area. */ accessory?: ComponentChildren; /** - * The breadcrumb actions to perform, provided as link elements. + * The navigation breadcrumb links displayed in the page header as link elements. These show the hierarchical path to the current page. */ breadcrumbActions?: ComponentChildren; /** - * The aside element is section of a page that contains content that is tangentially related to the content around the aside element, and which could be considered separate from that content. - * Such sections are often represented as sidebars in printed typography. + * The content to display in the page's sidebar. This area is for content that is tangentially related to the main content, such as navigation or contextual information. Use the `slot="aside"` attribute to place content in this area. + * * @implementation surfaces built ontop of the web platform should implement this using the