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 c3be074c81..db66ccad7d 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 @@ -36,8 +36,9 @@ const data: ReferenceEntityTemplateSchema = { 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.', + sectionContent: ` +The \`presentModal()\` method must be called from a user interaction (such as a button click or tile tap) and can't be invoked programmatically during extension initialization or from background operations. +`, }, ], examples: { @@ -50,7 +51,7 @@ const data: ReferenceEntityTemplateSchema = { '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.", + 'Present a full-screen modal from menu item actions in detail screens. This example shows how to use `shopify.action.presentModal()` to launch a modal workflow from post-purchase, order details, or other action menu item contexts. With this pattern, you can implement complex, multi-step operations.', }, { codeblock: generateJsxCodeBlockForActionApi( @@ -58,7 +59,7 @@ const data: ReferenceEntityTemplateSchema = { '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.", + 'Present a full-screen modal from smart grid tiles on the POS home screen. This example demonstrates using `shopify.action.presentModal()` to launch modal workflows from tile interactions. This pattern is well-suited for high-frequency tasks that require additional UI beyond the tile itself.', }, ], }, 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 0e804f0c76..b295ab550d 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 @@ -38,10 +38,9 @@ const data: ReferenceEntityTemplateSchema = { 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.', + sectionContent: ` +Cart operations may fail due to business rules, inventory constraints, oversell protection, or validation errors—always implement appropriate error handling. +`, }, ], examples: { @@ -54,7 +53,7 @@ const data: ReferenceEntityTemplateSchema = { '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.", + 'Add a custom item to the cart with manual pricing and details. This example demonstrates using `shopify.cart.addCustomSale()` to create custom line items for services, fees, or items not in the product catalog. This provides flexibility for unique sales scenarios.', }, { codeblock: generateJsxCodeBlockForCartApi( @@ -62,7 +61,7 @@ const data: ReferenceEntityTemplateSchema = { '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.", + 'Create a new address for the customer associated with the cart. This example demonstrates using `shopify.cart.addAddress()` to add shipping or billing addresses to customer profiles. This simplifies future purchases and enables multiple delivery locations.', }, { codeblock: generateJsxCodeBlockForCartApi( @@ -70,7 +69,7 @@ const data: ReferenceEntityTemplateSchema = { '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.", + 'Add a product variant to the cart with specified quantity and optional properties. This example shows how to use `shopify.cart.addLineItem()` to add catalog items to the cart with custom attributes. This enables standard product sales with additional customization.', }, { codeblock: generateJsxCodeBlockForCartApi( @@ -78,7 +77,7 @@ const data: ReferenceEntityTemplateSchema = { '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.', + 'Associate a subscription or selling plan with a line item for recurring purchases. This example shows how to use `shopify.cart.addLineItemSellingPlan()` to add selling plans to items. This enables subscription-based sales and recurring revenue models.', }, { codeblock: generateJsxCodeBlockForCartApi( @@ -86,23 +85,31 @@ const data: ReferenceEntityTemplateSchema = { '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.", + 'Attach custom metadata to a specific line item for additional product information. This example shows how to use `shopify.cart.addLineItemProperties()` to add key-value properties to individual items. This enables customization like engraving text, gift messages, or special instructions.', }, { codeblock: generateJsxCodeBlockForCartApi( - 'Add custom properties to multiple line items', + 'Add custom properties to the cart', + 'add-cart-properties', + ), + description: + 'Attach custom metadata to the cart for additional order information. This example shows how to use `shopify.cart.addCartProperties()` to add key-value properties that persist through checkout. This is useful for tracking order sources, preferences, or workflow data.', + }, + { + codeblock: generateJsxCodeBlockForCartApi( + 'Add properties to multiple line items at once', '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.', + 'Attach custom metadata to multiple line items efficiently in a single operation. This example demonstrates using `shopify.cart.bulkAddLineItemProperties()` to add properties to several items simultaneously. This improves performance for batch customization operations.', }, { codeblock: generateJsxCodeBlockForCartApi( - 'Add custom properties to the cart', - 'add-cart-properties', + 'Apply a cart-level discount', + 'apply-cart-discount', ), 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.", + 'Apply a custom discount to the entire cart using a fixed amount or percentage. This example shows how to use `shopify.cart.applyCartDiscount()` to add order-level discounts with custom reasons. This is useful for promotions, loyalty rewards, or staff discounts.', }, { codeblock: generateJsxCodeBlockForCartApi( @@ -110,7 +117,7 @@ const data: ReferenceEntityTemplateSchema = { '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.", + 'Apply a discount code to the cart for automatic discount validation and application. This example demonstrates using `shopify.cart.applyCodeDiscount()` to add discount codes that are validated against Shopify discount rules. This enables promotional code redemption with automatic validation.', }, { codeblock: generateJsxCodeBlockForCartApi( @@ -118,7 +125,7 @@ const data: ReferenceEntityTemplateSchema = { '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.", + 'Apply a custom discount to a specific line item in the cart. This example demonstrates using `shopify.cart.setLineItemDiscount()` to add item-level discounts with custom reasons. This is useful for selective price adjustments or item-specific promotions.', }, { codeblock: generateJsxCodeBlockForCartApi( @@ -134,7 +141,7 @@ const data: ReferenceEntityTemplateSchema = { '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.', + 'Apply discounts to multiple line items efficiently in a single operation. This example shows how to use `shopify.cart.bulkSetLineItemDiscounts()` to add discounts to several items simultaneously. This improves performance for bulk pricing adjustments or category-wide promotions.', }, { codeblock: generateJsxCodeBlockForCartApi( @@ -142,7 +149,7 @@ const data: ReferenceEntityTemplateSchema = { '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.', + 'Assign a customer to the current cart for personalized pricing and order history. This example demonstrates using `shopify.cart.setCustomer()` to link a customer by ID. This enables customer-specific discounts, loyalty programs, and order tracking.', }, { codeblock: generateJsxCodeBlockForCartApi( @@ -150,7 +157,7 @@ const data: ReferenceEntityTemplateSchema = { '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.', + 'Associate a specific line item with a staff member for item-level commission tracking. This example shows how to use `shopify.cart.setAttributedStaffToLineItem()` to assign staff members to individual items. This enables granular sales attribution and performance analysis.', }, { codeblock: generateJsxCodeBlockForCartApi( @@ -158,7 +165,7 @@ const data: ReferenceEntityTemplateSchema = { '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.', + 'Attribute the cart to a staff member for commission tracking and sales attribution. This example demonstrates using `shopify.cart.setAttributedStaff()` to assign staff members to sales. This enables performance tracking and commission calculations.', }, { codeblock: generateJsxCodeBlockForCartApi( @@ -166,7 +173,7 @@ const data: ReferenceEntityTemplateSchema = { '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.', + 'Verify whether the cart is in an editable state before attempting modifications. This example demonstrates using `shopify.cart.editable` to check if the cart can accept changes. By disabling actions when the cart is locked or in an immutable state, you can prevent errors and improve the user experience.', }, { codeblock: generateJsxCodeBlockForCartApi( @@ -174,7 +181,7 @@ const data: ReferenceEntityTemplateSchema = { '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.', + 'Remove all line items and reset the cart to an empty state. This example shows how to use `shopify.cart.clear()` to completely clear the cart. This is useful for starting fresh transactions or implementing cart reset functionality.', }, { codeblock: generateJsxCodeBlockForCartApi( @@ -182,71 +189,71 @@ const data: ReferenceEntityTemplateSchema = { '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.", + 'Remove a specific address from the customer profile using its unique identifier. This example shows how to use `shopify.cart.deleteAddress()` to delete outdated or incorrect addresses. This helps maintain clean customer records.', }, { codeblock: generateJsxCodeBlockForCartApi( - 'Monitor cart changes in real time', - 'subscribe', + 'Remove a discount from a line item', + 'remove-line-item-discount', ), 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.', + 'Remove a previously applied discount from a specific line item. This example demonstrates using `shopify.cart.removeLineItemDiscount()` to clear item-level discounts. This is useful for discount corrections or when promotional conditions are no longer met.', }, { codeblock: generateJsxCodeBlockForCartApi( - 'Remove a discount from a line item', - 'remove-line-item-discount', + 'Remove all discounts from cart and line items', + 'remove-all-discounts', ), 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.', + 'Clear all discounts applied to both the cart and individual line items in a single operation. This example shows how to use `shopify.cart.removeAllDiscounts()` to reset pricing to base values. This is useful for recalculating totals or canceling promotional offers.', }, { codeblock: generateJsxCodeBlockForCartApi( - 'Remove a product from the cart', + 'Remove an item 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.', + 'Remove a specific line item from the cart using its unique identifier. This example demonstrates using `shopify.cart.removeLineItem()` to delete items. This is useful for implementing remove buttons, cart cleanup, or conditional item removal logic.', }, { codeblock: generateJsxCodeBlockForCartApi( - 'Remove a subscription selling plan from a line item', - 'remove-line-item-selling-plan', + 'Remove custom properties from a line item', + 'remove-line-item-properties', ), 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.', + 'Delete specific custom properties from a line item by their keys. This example shows how to use `shopify.cart.removeLineItemProperties()` to clear item metadata. This is useful for removing temporary customization data or outdated property values.', }, { codeblock: generateJsxCodeBlockForCartApi( - 'Remove all discounts from the cart and line items', - 'remove-all-discounts', + 'Remove custom properties from the cart', + 'remove-cart-properties', ), 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.', + 'Delete specific custom properties from the cart by their keys. This example demonstrates using `shopify.cart.removeCartProperties()` to clear metadata. This is useful for cleaning up temporary data or removing properties that are no longer needed.', }, { codeblock: generateJsxCodeBlockForCartApi( - 'Remove custom properties from a line item', - 'remove-line-item-properties', + 'Remove a subscription plan from a line item', + 'remove-line-item-selling-plan', ), 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.', + 'Remove the selling plan from a line item to convert it back to a one-time purchase. This example demonstrates using `shopify.cart.removeLineItemSellingPlan()` to clear subscription plans. This is useful when customers change their mind about recurring orders.', }, { codeblock: generateJsxCodeBlockForCartApi( - 'Remove custom properties from the cart', - 'remove-cart-properties', + 'Remove the customer from the cart', + 'remove-customer', ), 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.', + 'Disassociate the customer from the current cart for anonymous transactions. This example shows how to use `shopify.cart.removeCustomer()` to clear customer information. This reverts to guest checkout pricing and removes customer-specific data from the cart.', }, { codeblock: generateJsxCodeBlockForCartApi( - 'Remove the customer from the cart', - 'remove-customer', + 'Subscribe to real-time cart changes', + 'subscribe', ), 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.', + 'Monitor cart state changes in real time using the subscribe method. This example shows how to use `shopify.cart.subscribe()` to receive updates whenever the cart changes. This enables reactive UI updates, validation logic, or analytics tracking based on cart modifications.', }, { codeblock: generateJsxCodeBlockForCartApi( @@ -254,7 +261,7 @@ const data: ReferenceEntityTemplateSchema = { '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.", + 'Designate a specific address as the default for the customer. This example demonstrates using `shopify.cart.updateDefaultAddress()` to set the primary shipping or billing address. This simplifies the checkout process for 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 5135aeaaf7..e625f88018 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 @@ -27,11 +27,11 @@ const data: ReferenceEntityTemplateSchema = { examples: [ { codeblock: generateJsxCodeBlockForCartLineItemApi( - 'Display the line item ID', + 'Retrieve 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.', + 'Access the unique identifier of the current cart line item in line item detail contexts. This example shows how to use `shopify.cartLineItem.id` to retrieve the line item ID. This can be used for modifying the item, applying discounts, or implementing item-specific functionality.', }, ], }, @@ -43,21 +43,22 @@ const data: ReferenceEntityTemplateSchema = { 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.', + sectionContent: ` +- **Handle optional properties:** Check for \`undefined\` in optional properties like \`price\`, \`productId\`, \`title\`, \`sku\`, and vendor before use. +- **Create contextual experiences:** Use line item data to show different interfaces for gift cards, subscriptions, or vendor-specific information. +- **Implement item-specific validation:** Use properties like \`taxable\`, \`isGiftCard\`, and \`requiresSellingPlan\` for appropriate business logic. +- **Handle selling plans:** When working with subscriptions, check \`requiresSellingPlan\` and \`sellingPlan\` to provide appropriate subscription management. +- **Access related data efficiently:** Use \`productId\` and \`variantId\` to fetch additional info when needed, but avoid unnecessary API calls. +`, }, { 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.", + sectionContent: ` +- Line item data reflects the current state and may not include real-time inventory, pricing, or selling plan updates until the cart is refreshed. +- 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 9e6a4f693b..98660643c5 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 @@ -38,10 +38,9 @@ const data: ReferenceEntityTemplateSchema = { 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.", + sectionContent: ` +Connectivity status reflects Internet connectivity only and may not indicate the quality or speed of the connection, which could affect API performance. +`, }, ], examples: { @@ -54,7 +53,7 @@ const data: ReferenceEntityTemplateSchema = { '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.', + 'Subscribe to connectivity changes to monitor network status in real time. This example demonstrates using `shopify.connectivity.subscribe()` and `shopify.connectivity.connected` to detect when the device goes online or offline. This enables adaptive behavior for offline-capable features or network-dependent operations.', }, ], }, 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 3a70014ed0..0c2c87abba 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 @@ -25,11 +25,11 @@ const data: ReferenceEntityTemplateSchema = { examples: [ { codeblock: generateJsxCodeBlockForCustomerApi( - 'Display the customer ID', + 'Retrieve 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.', + 'Access the unique identifier of the current customer in a customer detail context. This example shows how to use `shopify.customer.id` to retrieve the customer ID. This can be used for fetching additional customer data, implementing loyalty features, or building personalized customer experiences.', }, ], }, @@ -41,18 +41,19 @@ const data: ReferenceEntityTemplateSchema = { 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.', + sectionContent: ` +- **Use customer ID for lookups:** Fetch additional customer information from external systems or Shopify APIs using the customer ID. +- **Enable personalized features:** Use customer context for customer-specific pricing, loyalty programs, or product recommendations. +- **Validate customer access:** Verify the customer ID is valid before performing operations or API calls. +`, }, { 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.', + sectionContent: ` +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 1aea405bb1..14f2d76ca0 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 @@ -32,15 +32,6 @@ const data: ReferenceEntityTemplateSchema = { '- **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: @@ -52,23 +43,23 @@ const data: ReferenceEntityTemplateSchema = { '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.', + 'Check if the POS device is running on tablet hardware to adapt your UI accordingly. This example shows how to use `shopify.device.isTablet()` to determine the device form factor. This enables responsive layouts and touch-optimized interfaces for tablet devices versus traditional POS terminals.', }, { codeblock: generateJsxCodeBlockForDeviceApi( - 'Display the device ID', + 'Retrieve 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.', + 'Access the unique identifier of the current POS device. This example demonstrates using `shopify.device.id` to retrieve the device ID. This enables device-specific configurations, analytics tracking, or multi-device coordination features.', }, { codeblock: generateJsxCodeBlockForDeviceApi( - 'Display the device name', + 'Retrieve 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.', + 'Retrieve the name of the current POS device. This example shows how to use `shopify.device.name` to get the device name configured in POS settings. This is useful for device identification, multi-device workflows, or displaying location-specific information.', }, ], }, 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 3fed7a21fe..fcc1a4fc51 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 @@ -27,17 +27,19 @@ const data: ReferenceEntityTemplateSchema = { examples: [ { codeblock: generateJsxCodeBlockForDraftOrderApi( - 'Display the draft order ID', + 'Retrieve a 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.', + 'Access the unique identifier of the current draft order in a draft order detail context. This example shows how to use `shopify.draftOrder.id` to retrieve the draft order ID. This can be used for fetching additional order data, implementing custom workflows, or building draft order-specific features.', }, { codeblock: generateJsxCodeBlockForDraftOrderApi( "Retrieve a draft order's name, ID, and associated customer ID", 'draft-order-details', ), + description: + 'Access multiple properties from the draft order object including name, ID, and customer information. This example demonstrates using `shopify.draftOrder` to retrieve comprehensive draft order details. This enables building contextual interfaces and implementing order-specific workflows.', }, ], }, @@ -58,9 +60,9 @@ const data: ReferenceEntityTemplateSchema = { 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.', + sectionContent: ` +Draft order 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/locale-api.doc.ts b/packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/locale-api.doc.ts index 0913172e30..fdf771b3b6 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 @@ -32,15 +32,6 @@ const data: ReferenceEntityTemplateSchema = { '- **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: @@ -52,7 +43,7 @@ const data: ReferenceEntityTemplateSchema = { '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.", + "Subscribe to locale changes to monitor the merchant's language settings in real time. This example shows how to use `shopify.locale.subscribe()` and `shopify.locale.ianaCode` to detect when the merchant changes their language preference. This enables dynamic content localization and internationalized user experiences.", }, ], }, 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 f2f3335a53..0ce3aced37 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 @@ -43,10 +43,10 @@ const data: ReferenceEntityTemplateSchema = { 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.', + 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. +- Navigation state is limited to serializable data and can't contain functions, complex objects, or circular references. +`, }, ], examples: { @@ -59,7 +59,7 @@ const data: ReferenceEntityTemplateSchema = { '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.', + 'Create multi-screen workflows within your extension using web-standard navigation. This example demonstrates using `navigation.navigate()` to move between different screens in your modal interface. This enables complex multi-step processes with proper navigation history management.', }, { codeblock: generateJsxCodeBlockForNavigationApi( @@ -67,7 +67,7 @@ const data: ReferenceEntityTemplateSchema = { '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.', + 'Navigate to native POS screens from your extension using deep link URIs. This example shows how to use `navigation.navigate()` with POS screen URIs to transition to core POS functionality like cart, product details, or order screens. This enables direct transitions between your extension and native POS features.', }, { codeblock: generateJsxCodeBlockForNavigationApi( @@ -75,7 +75,7 @@ const data: ReferenceEntityTemplateSchema = { '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.', + 'Share data between screens using navigation state parameters. This example demonstrates using the `state` option in `navigation.navigate()` to pass data when navigating. This enables screens to receive context and maintain workflow continuity across navigation transitions.', }, ], }, 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 54ffddad40..594ffb6eb2 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 @@ -36,9 +36,9 @@ const data: ReferenceEntityTemplateSchema = { 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.', + sectionContent: ` +Order data reflects the current POS session and may not include real-time updates from other channels until the session is refreshed. +`, }, ], examples: { @@ -47,17 +47,19 @@ const data: ReferenceEntityTemplateSchema = { examples: [ { codeblock: generateJsxCodeBlockForOrderApi( - 'Display the order ID', + 'Retrieve an 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.', + '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. This can be used for fetching additional order data, tracking, or implementing order-specific functionality and post-purchase workflows.', }, { codeblock: generateJsxCodeBlockForOrderApi( "Retrieve an order's name, ID, and associated customer ID", 'order-details', ), + description: + 'Access multiple order properties including the order name and customer ID. This example demonstrates accessing `shopify.order.id`, `shopify.order.name`, and `shopify.order.customerId` to display comprehensive order information. Use this pattern for order management workflows and customer service features.', }, ], }, 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 27d3f6268d..e59fd15183 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 @@ -36,10 +36,9 @@ const data: ReferenceEntityTemplateSchema = { 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.', + 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. +`, }, ], examples: { @@ -52,13 +51,15 @@ const data: ReferenceEntityTemplateSchema = { '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.', + '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. By handling the entered PIN securely and processing the result, you can implement secure authentication workflows.', }, { codeblock: generateJsxCodeBlockForToastApi( 'Configure PinPad options and handle dismissal', 'validation-with-options', ), + description: + 'Configure PIN pad options including PIN length requirements, masking, and custom labels. This example shows how to use `showPinPad()` with options like `minPinLength`, `maxPinLength`, `masked`, `title`, and `onDismissed` callback. This creates a fully configured PIN entry experience with proper validation and dismissal handling.', }, ], }, 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 0062abef9f..2508bd0f6d 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 @@ -41,10 +41,9 @@ const data: ReferenceEntityTemplateSchema = { 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.', + sectionContent: ` +PDF printing on Android devices requires downloading the file and using an external application, which may interrupt the user workflow. +`, }, ], examples: { @@ -57,23 +56,23 @@ const data: ReferenceEntityTemplateSchema = { '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.', + '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. This allows quick printing of receipts, labels, or reports directly from the POS home screen.', }, { codeblock: generateJsxCodeBlockForPrintApi( - 'Print from a remote URL', + 'Print a document 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.', + '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. This enables dynamic content generation or printing from external services.', }, { codeblock: generateJsxCodeBlockForPrintApi( - 'Print using a relative file path', + 'Print a document 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.', + '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. This makes 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 324774e2f3..36c452e502 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 @@ -25,17 +25,19 @@ const data: ReferenceEntityTemplateSchema = { examples: [ { codeblock: generateJsxCodeBlockForProductApi( - 'Display the product ID', + 'Retrieve a 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.', + '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. This can be used for fetching additional product data, analytics, or implementing product-specific features and workflows.', }, { codeblock: generateJsxCodeBlockForProductApi( 'Retrieve product and product variant IDs', 'product-variant', ), + description: + 'Access both product and variant identifiers to implement variant-specific functionality. This example shows how to retrieve `shopify.product.id` and `shopify.product.variantId` together. Use this pattern for variant-aware features like inventory checks, variant-specific pricing, or detailed product information displays.', }, ], }, @@ -56,9 +58,9 @@ const data: ReferenceEntityTemplateSchema = { 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.', + sectionContent: ` +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 82a9bb28f1..12f9ed21a5 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 @@ -38,10 +38,10 @@ const data: ReferenceEntityTemplateSchema = { 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.', + sectionContent: ` +- Product search results are limited to products available on the current POS device and may not include the complete shop catalog if products aren't synced locally. +- Bulk operations (\`fetchProductsWithIds\` and \`fetchProductVariantsWithIds\`) are limited to 50 items maximum, with additional IDs automatically removed from requests. +`, }, ], examples: { @@ -50,43 +50,43 @@ const data: ReferenceEntityTemplateSchema = { examples: [ { codeblock: generateJsxCodeBlockForProductSearchApi( - 'Fetch multiple products by IDs', - 'fetch-products-with-ids', + 'Fetch a single product by ID', + 'fetch-product-with-id', ), 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.', + 'Fetch a single product by 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 variants by IDs', - 'fetch-product-variants-with-ids', + 'Fetch a single variant by ID', + 'fetch-product-variant-with-id', ), 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.', + 'Fetch a single variant by 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 paginated variants for a product', - 'fetch-paginated-product-variants-with-product-id', + 'Fetch multiple products by IDs', + 'fetch-products-with-ids', ), 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.', + 'Fetch multiple products by IDs. This example shows how to use `shopify.productSearch.fetchByIds()` to efficiently fetch data for multiple products in a single request. This improves performance when displaying product lists or related items.', }, { codeblock: generateJsxCodeBlockForProductSearchApi( - 'Fetch a single product by ID', - 'fetch-product-with-id', + 'Fetch multiple variants by IDs', + 'fetch-product-variants-with-ids', ), 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.', + 'Fetch multiple variants by IDs. This example shows how to use `shopify.productSearch.fetchVariantsByIds()` to efficiently fetch data for multiple variants in a single request. This is useful for displaying variant lists or comparisons.', }, { codeblock: generateJsxCodeBlockForProductSearchApi( - 'Fetch a single variant by ID', - 'fetch-product-variant-with-id', + 'Fetch paginated variants for a product', + 'fetch-paginated-product-variants-with-product-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.', + 'Fetch paginated variants for a product. This example demonstrates using `shopify.productSearch.fetchVariantsByProductId()` with pagination parameters to load variants page by page. This improves performance and user experience for products with large variant catalogs.', }, { codeblock: generateJsxCodeBlockForProductSearchApi( @@ -94,7 +94,7 @@ const data: ReferenceEntityTemplateSchema = { '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.', + 'Search for products using a search bar. This example shows how to use `shopify.productSearch.search()` to perform text-based product searches with pagination support. This allows 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 69ee2dae34..8848c7dc4e 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 @@ -27,20 +27,21 @@ const data: ReferenceEntityTemplateSchema = { 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.', + sectionContent: ` +- **Handle scan events reactively:** Use \`subscribe\` methods to process scan events as they occur for immediate feedback. +- **Validate scanned data:** Validate before processing and handle invalid codes, unsupported formats, or errors. +- **Provide clear feedback:** Show success confirmations, error messages, and guidance when scans fail. +- **Adapt to available sources:** Check available scanner sources and provide alternatives when preferred methods aren't available. +- **Handle scan data processing:** Scan data processing is reactive and requires proper subscription management to avoid memory leaks or unexpected behavior when components unmount. +`, }, { 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.', + sectionContent: ` +The Scanner API is only available in action (modal) targets where scanning functionality is supported and can't be used in other targets. +`, }, ], examples: { @@ -53,13 +54,15 @@ const data: ReferenceEntityTemplateSchema = { '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.', + '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). By identifying the scanner type, you can customize handling based on the scanning method.', }, { codeblock: generateCodeBlockForScannerApi( 'Subscribe to scanner data events and track scanning history', 'scanner-data-subscribe', ), + description: + 'Subscribe to real-time scan events and maintain a history of scanned items. This example demonstrates using `shopify.scanner.scannerData.current.subscribe()` to capture scan data, source information, and timestamps. Use this pattern for scan logging, bulk scanning workflows, or scan history review.', }, ], }, 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 eb11587435..ba682c7936 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 @@ -36,10 +36,10 @@ const data: ReferenceEntityTemplateSchema = { 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.", + sectionContent: ` +- Session tokens are only available when the authenticated user has proper app permissions enabled—staff members who are pinned in but not authenticated can't generate tokens. +- Session 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: { @@ -48,17 +48,19 @@ const data: ReferenceEntityTemplateSchema = { examples: [ { codeblock: generateJsxCodeBlockForSessionApi( - 'Access session data and generate authentication tokens', - 'token', + 'Access properties associated with the current session', + 'current-session', ), 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.', + 'Access comprehensive session information including shop details, user data, and location information. This example shows how to use `shopify.session.currentSession` to retrieve the shop ID, domain, currency, user ID, location ID, staff member ID, and POS version. Use this data to build location-aware features and personalized experiences.', }, { codeblock: generateJsxCodeBlockForSessionApi( - 'Access properties associated with the current session', - 'current-session', + 'Access session data and generate authentication tokens', + 'token', ), + description: + 'Access session data and generate authentication tokens. 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.', }, ], }, 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 02105fe74b..2571fc2993 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 @@ -14,35 +14,34 @@ const data: ReferenceEntityTemplateSchema = { category: 'Target APIs', subCategory: 'Standard APIs', related: [], + definitions: [ + { + title: 'StorageApi', + 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', + }, + ], 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.', + sectionContent: ` +- **Design consistent key naming:** Use hierarchical names like \`settings.user.theme\` or \`cache.products.\${id}\` to organize data. +- **Validate retrieved data:** Check structure and types after \`get()\` since data may be outdated. Provide defaults and handle missing properties. +- **Plan for data evolution:** Include version fields and implement migration logic to handle schema updates between versions. +- **Keep sensitive data out:** Never store passwords, API keys, or sensitive information. Use Session API for secure backend communication. +`, }, { 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: - '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', + sectionContent: ` +- POS UI extensions can store up to a maximum of 100 entries. +- Stored extension data is automatically cleared after 30 days of inactivity. +`, }, ], examples: { @@ -55,7 +54,7 @@ const data: ReferenceEntityTemplateSchema = { '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.', + '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. This is useful for reset functionality or clearing user preferences.', }, { codeblock: generateJsxCodeBlockForStorageApi( @@ -63,7 +62,7 @@ const data: ReferenceEntityTemplateSchema = { '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.', + 'Delete a specific value from storage using its key. This example shows how to use `shopify.storage.delete()` to remove a stored item. This permanently clears the data associated with that key while leaving other stored values intact.', }, { codeblock: generateJsxCodeBlockForStorageApi( @@ -71,7 +70,7 @@ const data: ReferenceEntityTemplateSchema = { '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.', + '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. This is useful for displaying saved data, performing bulk operations, or exporting stored information.', }, { codeblock: generateJsxCodeBlockForStorageApi( @@ -79,7 +78,7 @@ const data: ReferenceEntityTemplateSchema = { '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.', + '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. This returns the stored data with automatic JSON deserialization or undefined if the key does not exist.', }, { codeblock: generateJsxCodeBlockForStorageApi( @@ -87,7 +86,7 @@ const data: ReferenceEntityTemplateSchema = { '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.', + 'Store a value in persistent storage using a key-value pair. This example demonstrates using `shopify.storage.set()` to save data that persists across user sessions, device restarts, and extension reloads. The value is automatically JSON serialized.', }, ], }, 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 3b088b7dff..f41f584f96 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 @@ -26,20 +26,21 @@ const data: ReferenceEntityTemplateSchema = { 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.', + sectionContent: ` +- **Write clear, concise messages:** Keep content brief since toasts disappear automatically. +- **Use appropriate timing:** Choose durations that give users enough time to read without keeping visible too long. +- **Provide meaningful feedback:** Use toasts to confirm actions, explain errors, or communicate status changes. +- **Avoid overuse:** Reserve for important feedback. Don't show multiple toasts simultaneously. +- **Handle multiple toast messages:** Multiple toast messages may overlap or interfere with each other if shown in rapid succession. Consider queuing or spacing out notifications appropriately. +`, }, { 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.", + sectionContent: ` +Toast content is limited to plain text and can't include rich formatting, links, or interactive elements. +`, }, ], examples: { @@ -48,17 +49,19 @@ const data: ReferenceEntityTemplateSchema = { examples: [ { codeblock: generateJsxCodeBlockForToastApi( - 'Display a toast notification from a tile', - 'show', + 'Display a toast notification for a custom duration', + 'show-with-duration', ), 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.", + 'Configure custom display durations for toast notifications to match message importance and length. This example demonstrates using the `duration` option with `shopify.toast.show()` to control how long notifications remain visible. Use shorter durations for quick confirmations and longer durations for messages that require more reading time.', }, { codeblock: generateJsxCodeBlockForToastApi( - 'Display a toast notification for a custom duration', - 'show-with-duration', + 'Display a toast notification from a tile', + 'show', ), + description: + "Display a toast notification from a tile. This example demonstrates using `shopify.toast.show()` to display a brief, non-intrusive message that automatically disappears after a specified duration. This is useful for confirmations, status updates, or success messages that don't require user interaction.", }, ], }, diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/Badge/Badge.doc.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/Badge/Badge.doc.ts index 7d6aeb79c7..f5b1f12fb7 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/Badge/Badge.doc.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/Badge/Badge.doc.ts @@ -3,8 +3,9 @@ import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs'; const data: ReferenceEntityTemplateSchema = { name: 'Badge', description: - 'The `Badge` component uses color and text to communicate status information for orders, products, customers, and other business data. Use badges to create visual hierarchy and help merchants quickly identify important information or status changes within your POS interface.' + - '\n\nThe component automatically adjusts its appearance based on the specified `tone` property, ensuring consistent visual communication across the POS interface. Badges support different sizes and can display text, numbers, or status indicators, making them versatile for representing everything from order counts to inventory alerts in a compact, scannable format.', + "The `Badge` component uses color and text to communicate status information for orders, products, customers, and other business data. Badges aren't interactive elements; they display information but don't respond to user interactions like clicks or taps. Use badges to create visual hierarchy and help merchants quickly identify important information or status changes within your POS interface. " + + '\n\nThe component automatically adjusts its appearance based on the specified `tone` property, ensuring consistent visual communication across the POS interface. The component relies on the tone system for semantic meaning, so using custom styling with badges may not clearly convey meaning to merchants.' + + '\n\nBadges support different sizes and can display text, numbers, or status indicators. This makes them versatile for representing everything from order counts to inventory alerts in a compact, scannable format.', thumbnail: 'badge-thumbnail.png', isVisualComponent: true, type: '', @@ -37,20 +38,19 @@ const data: ReferenceEntityTemplateSchema = { type: 'Generic', anchorLink: 'best-practices', title: 'Best practices', - sectionContent: - '- **Apply appropriate tones:** Use `success` for positive states, `critical` for urgent issues, `warning` for attention-needed states, `info` for neutral information.\n' + - "- **Keep text brief:** Use single words or short phrases. Avoid lengthy descriptions that don't fit the compact design.\n" + - '- **Position near related content:** Place badges next to the items they describe for clear associations.\n' + - '- **Use for status, not actions:** Badges display information only. For interactive elements, use buttons or clickable components.', + sectionContent: ` +- **Apply appropriate tones:** Use \`success\` for positive states, \`critical\` for urgent issues, \`warning\` for attention-needed states, \`info\` for neutral information. +- **Keep text brief:** Use single words or short phrases. Avoid lengthy descriptions that don't fit the compact design. +- **Position near related content:** Place badges next to the items they describe for clear associations. +- **Use for status, not actions:** Badges display information only. For interactive elements, use buttons or clickable components. +`, }, { type: 'Generic', anchorLink: 'limitations', title: 'Limitations', - sectionContent: - "- Badges aren't interactive elements—they display information but don't respond to user interactions like clicks or taps.\n" + - '- The component relies on the tone system for semantic meaning, so custom styling may not convey the same semantic benefits.\n' + - '- Very long text content may be truncated or cause layout issues depending on the container and screen size.', + sectionContent: ` +Very long text content may be truncated or cause layout issues depending on the container and screen size.`, }, ], related: [], diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/Banner/Banner.doc.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/Banner/Banner.doc.ts index 2d9abe7861..3b045443d3 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/Banner/Banner.doc.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/Banner/Banner.doc.ts @@ -4,7 +4,8 @@ const data: ReferenceEntityTemplateSchema = { name: 'Banner', description: 'The `Banner` component highlights important information or required actions prominently within the POS interface. Use banners to communicate critical updates, warnings, informational messages, or success notifications that require merchant attention in a persistent but non-interruptive way.' + - '\n\nThe component provides persistent visibility for important messages while remaining non-intrusive to the main workflow, with support for dismissible and non-dismissible states. It includes automatic color coding based on message severity and integrates with the POS design system to maintain visual consistency across different alert types and use cases.', + '\n\nThe component provides persistent visibility for important messages while remaining non-intrusive to the main workflow, with support for dismissible and non-dismissible states. It includes automatic color coding based on message severity and integrates with the POS design system to maintain visual consistency across different alert types and use cases.' + + "\n\nThe `Banner` component only accepts a `heading` property for text content and doesn't support body content. You can't place `` or other text elements inside the banner as children.", thumbnail: 'banner-thumbnail.png', isVisualComponent: true, type: '', @@ -43,20 +44,14 @@ const data: ReferenceEntityTemplateSchema = { type: 'Generic', anchorLink: 'best-practices', title: 'Best practices', - sectionContent: - '- **Apply appropriate tones:** Use `critical` for errors requiring immediate action, `warning` for important notices, `success` for confirmations, `info` for general information.\n' + - '- **Keep headings concise:** Write brief headings that clearly communicate the message. Use the collapsible feature for additional detail.\n' + - '- **Show one banner at a time:** Display only one banner to avoid overwhelming the interface. Prioritize by importance.\n' + - '- **Make non-critical banners dismissible:** Allow dismissal for non-critical information. Keep critical alerts non-dismissible until resolved.\n' + - '- **Include clear actions:** If action is needed, use the primaryAction slot to provide clear next steps.\n' + - '- **Use for persistent messages:** Use banners for messages that need to persist. For temporary notifications, consider toast notifications.', - }, - { - type: 'Generic', - anchorLink: 'limitations', - title: 'Limitations', - sectionContent: - "- The `Banner` component only accepts a `heading` property for text content and doesn't support body content. You can't place `` or other text elements inside the banner as children.", + sectionContent: ` +- **Apply appropriate tones:** Use \`critical\` for errors requiring immediate action, \`warning\` for important notices, \`success\` for confirmations, \`info\` for general information. +- **Keep headings concise:** Write brief headings that clearly communicate the message. Use the collapsible feature for additional detail. +- **Show one banner at a time:** Display only one banner to avoid overwhelming the interface. Prioritize by importance. +- **Make non-critical banners dismissible:** Allow dismissal for non-critical information. Keep critical alerts non-dismissible until resolved. +- **Include clear actions:** If action is needed, use the primaryAction slot to provide clear next steps. +- **Use for persistent messages:** Use banners for messages that need to persist. For temporary notifications, consider toast notifications. +`, }, ], related: [], diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/Box/Box.doc.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/Box/Box.doc.ts index 72ff07cf29..9fe9809a3f 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/Box/Box.doc.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/Box/Box.doc.ts @@ -3,9 +3,10 @@ import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs'; const data: ReferenceEntityTemplateSchema = { name: 'Box', description: - 'The `Box` component displays a generic container with consistent spacing and styling. Use it to apply padding, to nest and group other components, or as the foundation for building structured layouts.' + - '\n\nThe component provides granular control over spacing through padding properties and sizing through width/height properties, serving as a building block for precise layouts. It simplifies the creation of containers with consistent spacing by using design system tokens, ensuring visual consistency and reducing the need for custom CSS in most layout scenarios.' + - '\n\n`Box` components provide shorthand properties for common padding patterns like equal padding on all sides or symmetric horizontal/vertical padding, reducing verbose property specifications for simpler layouts.', + "The `Box` component displays a generic container with consistent spacing and styling. Use it to apply padding, to nest and group other components, or as the foundation for building structured layouts. Box doesn't provide interactive functionality. For user interaction, use boxes in combination with interactive components like [`Button`](/docs/api/pos-ui-extensions/2025-10/polaris-web-components/actions/button) or [`Clickable`](/docs/api/pos-ui-extensions/2025-10/polaris-web-components/actions/clickable)." + + "\n\nThe component provides granular control over spacing through padding properties and sizing through width/height properties, serving as a building block for precise layouts. It simplifies the creation of containers with consistent spacing by using design system tokens, ensuring visual consistency and reducing the need for custom CSS in most layout scenarios. To maintain consistency, `Box` only supports predefined design system scales. Custom pixel values for padding aren't supported." + + '\n\n`Box` components provide shorthand properties for common padding patterns like equal padding on all sides or symmetric horizontal/vertical padding, reducing verbose property specifications for simpler layouts.' + + "\n\n`Box` doesn't provide scrolling capabilities for overflow content. When content exceeds the container dimensions, use [`ScrollBox`](/docs/api/pos-ui-extensions/2025-10/polaris-web-components/layout-and-structure/scrollbox) instead.", thumbnail: 'box-thumbnail.png', isVisualComponent: true, type: '', @@ -18,27 +19,6 @@ const data: ReferenceEntityTemplateSchema = { ], category: 'Polaris web components', subCategory: 'Layout and structure', - subSections: [ - { - type: 'Generic', - anchorLink: 'best-practices', - title: 'Best practices', - sectionContent: - '- **Use semantic sizing:** Choose `auto` to adapt to content, percentages for responsive layouts, pixels only for exact dimensions.\n' + - '- **Use design system padding:** Use predefined padding keywords (`small`, `base`, `large`) for consistency.\n' + - '- **Use directional padding for asymmetry:** Use `paddingInline` and `paddingBlock` when different spacing is needed on different sides.\n' + - '- **Understand block vs inline:** `block` refers to content flow direction (usually vertical), `inline` to text direction (usually horizontal).', - }, - { - type: 'Generic', - anchorLink: 'limitations', - title: 'Limitations', - sectionContent: - "- Box is a layout container and doesn't provide interactive functionality—use it in combination with interactive components like `Button` or `Clickable` for user interactions.\n" + - "- Padding values are limited to the predefined design system scale—custom pixel values for padding aren't supported to maintain design consistency.\n" + - "- Box doesn't provide scrolling capabilities for overflow content—use ScrollBox when content might exceed container dimensions.", - }, - ], defaultExample: { image: 'box-default.png', description: @@ -53,6 +33,19 @@ const data: ReferenceEntityTemplateSchema = { ], }, }, + subSections: [ + { + type: 'Generic', + anchorLink: 'best-practices', + title: 'Best practices', + sectionContent: ` +- **Use semantic sizing:** Choose \`auto\` to adapt to content, percentages for responsive layouts, pixels only for exact dimensions. +- **Use design system padding:** Use predefined padding keywords (\`small\`, \`base\`, \`large\`) for consistency. +- **Use directional padding for asymmetry:** Use \`paddingInline\` and \`paddingBlock\` when different spacing is needed on different sides. +- **Understand block vs inline:** \`block\` refers to content flow direction (usually vertical), \`inline\` to text direction (usually horizontal). +`, + }, + ], related: [], }; diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/Button/Button.doc.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/Button/Button.doc.ts index 2194d5673d..7865e35513 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/Button/Button.doc.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/Button/Button.doc.ts @@ -3,8 +3,10 @@ import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs'; const data: ReferenceEntityTemplateSchema = { name: 'Button', description: - 'The `Button` component triggers actions or events, such as opening dialogs or navigating to other pages. Use `Button` to let merchants perform specific tasks or initiate interactions throughout the POS interface.' + - '\n\nButtons provide clear calls-to-action that guide merchants through workflows, enable form submissions, and trigger important operations. They support various visual styles, tones, and interaction patterns to communicate intent and hierarchy within the interface.', + 'The `Button` component triggers actions or events, such as opening dialogs or navigating to other pages. Use `Button` to let merchants perform specific tasks or to initiate interactions throughout the POS interface.' + + "\n\n Button content must be plain text. If you nest components inside a button, the button extracts and displays only the text content from those components. For example, placing an `s-icon` inside a button won't display the icon, only its text content. Use of nested interactive components within buttons isn't supported." + + '\n\nButtons provide clear calls-to-action that guide merchants through workflows, enable form submissions, and trigger important operations. They support various visual styles, tones, and interaction patterns to communicate intent and hierarchy within the interface.' + + "\n\nLoading states replace all button content with a spinner. Custom loading indicators or partial content updates aren't supported.", thumbnail: 'button-thumbnail.png', isVisualComponent: true, type: '', @@ -24,28 +26,6 @@ const data: ReferenceEntityTemplateSchema = { ], category: 'Polaris web components', subCategory: 'Actions', - subSections: [ - { - type: 'Generic', - anchorLink: 'best-practices', - title: 'Best practices', - sectionContent: - '- **Write action-oriented text:** Use specific, actionable language like "Save customer" or "Process payment" rather than generic terms like "OK" or "Submit."\n' + - '- **Choose appropriate variants and tones:** Use `primary` for the main action and `secondary` for supporting actions. Use `critical` for destructive actions, `caution` or `warning` for actions requiring attention.\n' + - '- **Show loading states:** Set `loading` to `true` during async operations to prevent duplicate submissions.\n' + - '- **Use command system for component control:** Use `commandFor` and `command` to control modals and overlays declaratively.\n' + - '- **Structure hierarchies clearly:** Group related actions together. Separate destructive actions to prevent accidental activation.', - }, - { - type: 'Generic', - anchorLink: 'limitations', - title: 'Limitations', - sectionContent: - "- Button content must be plain text. If you nest components inside a button, the button extracts and displays only the text content from those components. For example, placing an `s-icon` inside a button won't display the icon—only any text content will be rendered. HTML, markdown, or rich text formatting isn't supported.\n" + - "- Loading states replace all button content with a spinner. Custom loading indicators or partial content updates aren't supported.\n" + - "- Complex button layouts or nested interactive components within buttons aren't supported.", - }, - ], defaultExample: { image: 'button-default.png', description: @@ -60,6 +40,20 @@ const data: ReferenceEntityTemplateSchema = { ], }, }, + subSections: [ + { + type: 'Generic', + anchorLink: 'best-practices', + title: 'Best practices', + sectionContent: ` +- **Write action-oriented text:** Use specific, actionable language like "Save customer" or "Process payment" rather than generic terms like "OK" or "Submit." +- **Choose appropriate variants and tones:** Use \`primary\` for the main action and \`secondary\` for supporting actions. Use \`critical\` for destructive actions, \`caution\` or \`warning\` for actions requiring attention. +- **Show loading states:** Set \`loading\` to \`true\` during async operations to prevent duplicate submissions. +- **Use command system for component control:** Use \`commandFor\` and \`command\` to control modals and overlays declaratively. +- **Structure hierarchies clearly:** Group related actions together. Separate destructive actions to prevent accidental activation. +`, + }, + ], related: [], }; diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/ChoiceList/ChoiceList.doc.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/ChoiceList/ChoiceList.doc.ts index 48394e75b4..f6402f8d58 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/ChoiceList/ChoiceList.doc.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/ChoiceList/ChoiceList.doc.ts @@ -4,8 +4,9 @@ const data: ReferenceEntityTemplateSchema = { name: 'ChoiceList', description: 'The `ChoiceList` component presents multiple options for single or multiple selections. Use it when merchants need to choose from a defined set of options in forms or filtering interfaces.' + - '\n\nThe component supports both single and multiple selection modes with clear visual indicators for selected states and proper checkbox or radio button semantics. It includes features like select all/none functionality for multiple selection across various configuration and filtering scenarios.' + - '\n\n`ChoiceList` components maintain selection state across navigation and form resets, with proper visual indication of indeterminate states when some but not all options in a group are selected.', + '\n\nThe component supports both single and multiple selection modes with clear visual indicators for selected states and proper checkbox or radio button semantics, although the actual appearance may vary based on the POS platform and screen size. It includes features like select all/none functionality for multiple selection across various configuration and filtering scenarios.' + + '\n\n`ChoiceList` components maintain selection state across navigation and form resets, with proper visual indication of indeterminate states when some but not all options in a group are selected. Within `ChoiceList`, use only `Choice` components as children.' + + "\n\n`ChoiceList` doesn't automatically filter or update content based on selections. You must implement the logic to respond to selection changes.", thumbnail: 'choicelist-thumbnail.png', isVisualComponent: true, type: '', @@ -31,25 +32,6 @@ const data: ReferenceEntityTemplateSchema = { ], category: 'Polaris web components', subCategory: 'Forms', - subSections: [ - { - type: 'Generic', - anchorLink: 'best-practices', - title: 'Best practices', - sectionContent: - '- **Choose appropriate selection modes:** Use single selection for mutually exclusive options. Enable `multiple` when merchants can select more than one.\n' + - '- **Write clear, concise choice labels:** Keep labels short but descriptive enough that merchants understand each option without additional explanation.', - }, - { - type: 'Generic', - anchorLink: 'limitations', - title: 'Limitations', - sectionContent: - "- `ChoiceList` requires choice components as children—other component types can't be used as options within the choice list.\n" + - "- The component provides the selection interface but doesn't automatically filter or update content based on selections—you must implement the logic to respond to selection changes.\n" + - '- Visual variants have different presentations across devices and contexts—the actual appearance may vary based on the POS platform and screen size.', - }, - ], defaultExample: { image: 'choicelist-default.png', description: @@ -64,6 +46,24 @@ const data: ReferenceEntityTemplateSchema = { ], }, }, + subSections: [ + { + type: 'Generic', + anchorLink: 'best-practices', + title: 'Best practices', + sectionContent: ` +- **Choose appropriate selection modes:** Use single selection for mutually exclusive options. Enable \`multiple\` when merchants can select more than one. +- **Write clear, concise choice labels:** Keep labels short but descriptive enough that merchants understand each option without additional explanation. +`, + }, + { + type: 'Generic', + anchorLink: 'limitations', + title: 'Limitations', + sectionContent: ` +\`ChoiceList\` component types other than \`Choice\` can't be used as options within the choice list.`, + }, + ], related: [], examples: { description: diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/Clickable/Clickable.doc.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/Clickable/Clickable.doc.ts index 1cb695f3a2..e3d9c16377 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/Clickable/Clickable.doc.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/Clickable/Clickable.doc.ts @@ -4,7 +4,9 @@ const data: ReferenceEntityTemplateSchema = { name: 'Clickable', description: 'The `Clickable` component makes any content interactive to user interactions. Use it to add click interactions to non-interactive elements while maintaining full control over their visual presentation.' + - "\n\nThis component provides a flexible way to wrap any content and make it respond to user interactions. Unlike buttons, it doesn't impose visual styling, allowing you to create custom interactive elements that match your design requirements while ensuring proper event handling.", + "\n\nThis component provides a flexible way to wrap any content and make it respond to user interactions. Unlike buttons, it doesn't impose visual styling, allowing you to create custom interactive elements that match your design requirements while ensuring proper event handling." + + "\n\n`Clickable` provides built-in `onClick` feedback, but because it doesn't impose visual styling, you must implement focus indicators and other visual cues yourself." + + '\n\nWhen disabled, child elements can still receive focus and be interacted with. Be careful when using nested interactive elements within `Clickable` components to avoid event propagation conflicts and unexpected user experiences.', thumbnail: 'clickable-thumbnail.png', isVisualComponent: true, type: '', @@ -24,27 +26,6 @@ const data: ReferenceEntityTemplateSchema = { ], category: 'Polaris web components', subCategory: 'Actions', - subSections: [ - { - type: 'Generic', - anchorLink: 'best-practices', - title: 'Best practices', - sectionContent: - '- **Ensure sufficient hit area:** Provide enough space around clickable elements for easy tap targets, especially on touch devices.\n' + - "- **Use for custom interactive elements:** Reserve `Clickable` for scenarios where `Button` styling isn't appropriate.\n" + - '- **Provide visual feedback:** Ensure wrapped content shows clear visual feedback on interaction through styling or state changes.\n' + - '- **Use command system when appropriate:** Use `commandFor` and `command` to control modals and overlays declaratively rather than through manual state management.', - }, - { - type: 'Generic', - anchorLink: 'limitations', - title: 'Limitations', - sectionContent: - "- `Clickable` doesn't provide built-in visual styling—you must design and implement all visual feedback and states for wrapped content.\n" + - "- The component doesn't automatically handle keyboard navigation for complex interactive patterns—implement additional keyboard handlers if needed.\n" + - '- Nested clickable elements can create confusing interactions—avoid placing clickable content inside other clickable containers.', - }, - ], defaultExample: { image: 'clickable-default.png', description: @@ -59,6 +40,26 @@ const data: ReferenceEntityTemplateSchema = { ], }, }, + subSections: [ + { + type: 'Generic', + anchorLink: 'best-practices', + title: 'Best practices', + sectionContent: ` +- **Implement visual feedback:** Since \`Clickable\` has no built-in styling, add focus indicators and active states to show interactivity. +- **Wrap non-interactive elements:** Use \`Clickable\` for text, images, or icons. Avoid wrapping components with built-in interactions. +- **Handle disabled state carefully:** When \`disabled\`, child elements can still receive focus. Provide visual feedback for the non-interactive state. +`, + }, + { + type: 'Generic', + anchorLink: 'limitations', + title: 'Limitations', + sectionContent: ` +The component doesn't automatically provide keyboard navigation support beyond basic click functionality. +`, + }, + ], related: [], }; diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/DateField/DateField.doc.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/DateField/DateField.doc.ts index 3a9e0ad60b..484cff975d 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/DateField/DateField.doc.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/DateField/DateField.doc.ts @@ -4,8 +4,8 @@ const data: ReferenceEntityTemplateSchema = { name: 'DateField', description: 'The `DateField` component captures date input with a consistent interface for date selection and proper validation. Use it to collect date information in forms, scheduling interfaces, or data entry workflows.' + - '\n\n`DateField` components support both manual text entry and picker selection, giving merchants flexibility to choose their preferred input method based on personal preference and specific date entry scenarios.' + - '\n\nFor visual calendar-based selection, consider `DatePicker`. For space-constrained layouts with scrolling date selection, use `DateSpinner`.', + '\n\n`DateField` accepts values in ISO 8601 format (`YYYY-MM-DD`). Other date formats require conversion before setting the value property. Validation of the entered date occurs when the user finishes editing, rather than on every keystroke, so invalid dates are flagged after blur. This can delay error feedback, so consider this in your design.' + + '\n\n`DateField` components support manual text entry. For visual calendar-based selection, consider using [`DatePicker`](/docs/api/pos-ui-extensions/2025-10/polaris-web-components/forms/datepicker) or [`DateSpinner`](/docs/api/pos-ui-extensions/2025-10/polaris-web-components/forms/datespinner) components.', thumbnail: 'date-field-thumbnail.png', isVisualComponent: true, type: '', @@ -25,26 +25,6 @@ const data: ReferenceEntityTemplateSchema = { ], category: 'Polaris web components', subCategory: 'Forms', - subSections: [ - { - type: 'Generic', - anchorLink: 'best-practices', - title: 'Best practices', - sectionContent: - '- **Choose for direct text input:** Use `DateField` when users know the exact date and can type it efficiently. Use `DatePicker` for calendar selection or `DateSpinner` for space-constrained layouts.\n' + - '- **Explain date constraints:** Use `details` to clarify requirements like "Select a date within the next 30 days" or "Must be a future date."\n' + - '- **Write actionable error messages:** Provide clear validation messages for invalid dates that help users correct their input.', - }, - { - type: 'Generic', - anchorLink: 'limitations', - title: 'Limitations', - sectionContent: - '- `DateField` accepts date values in [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601) (`YYYY-MM-DD`)—other date formats require conversion before setting the value property.\n' + - '- Validation occurs when the user finishes editing rather than on every keystroke—invalid dates are only flagged after blur, which may delay error feedback.\n' + - '- The component provides text-based date input—for calendar-style date selection, use the `DatePicker` component which offers visual date selection interface.', - }, - ], defaultExample: { image: 'date-field-default.png', description: @@ -59,6 +39,18 @@ const data: ReferenceEntityTemplateSchema = { ], }, }, + subSections: [ + { + type: 'Generic', + anchorLink: 'best-practices', + title: 'Best practices', + sectionContent: ` +- **Choose for direct text input:** Use \`DateField\` when users know the exact date and can type it efficiently. Use [\`DatePicker\`](/docs/api/pos-ui-extensions/2025-10/polaris-web-components/forms/datepicker) for calendar selection or [\`DateSpinner\`](/docs/api/pos-ui-extensions/2025-10/polaris-web-components/forms/datespinner) for space-constrained layouts. +- **Explain date constraints:** Use \`details\` to clarify requirements like "Select a date within the next 30 days" or "Must be a future date." +- **Write actionable error messages:** Provide clear validation messages for invalid dates that help users correct their input. +`, + }, + ], related: [], examples: { description: diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/DatePicker/DatePicker.doc.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/DatePicker/DatePicker.doc.ts index dc5b44e235..68175e0629 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/DatePicker/DatePicker.doc.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/DatePicker/DatePicker.doc.ts @@ -4,7 +4,9 @@ const data: ReferenceEntityTemplateSchema = { name: 'DatePicker', description: 'The `DatePicker` component allows merchants to select a specific date using a calendar-like picker interface. Use it to provide visual date selection with an intuitive calendar view for improved user experience.' + - '\n\n`DatePicker` offers a calendar-based alternative to spinner-style pickers when visual calendar context is beneficial. The calendar interface allows merchants to see dates in context of the full month, making it easier to select dates relative to specific days of the week or to visualize date ranges within a month view.', + '\n\n`DatePicker` offers a calendar-based alternative to [spinner-style pickers](/docs/api/pos-ui-extensions/2025-10/polaris-web-components/forms/datespinner) when visual calendar context is beneficial. The calendar interface allows merchants to see dates in context of the full month, making it easier to select dates relative to specific days of the week or to visualize date ranges within a month view.' + + '\n\nThe component supports single dates, multiple dates, and date ranges. This is achieved through value format alone—the selection mode is inferred from the `value` property format rather than an explicit property.' + + "\n\n`DatePicker` provides the calendar interface but requires external state management for the selected value. You must update the `value` property in response to change events. Invalid date values result in no date being selected. The component doesn't provide specific error feedback, so you must validate date formats before setting the `value` property.", thumbnail: 'date-picker-thumbnail.png', isVisualComponent: true, type: '', @@ -24,25 +26,6 @@ const data: ReferenceEntityTemplateSchema = { ], category: 'Polaris web components', subCategory: 'Forms', - subSections: [ - { - type: 'Generic', - anchorLink: 'best-practices', - title: 'Best practices', - sectionContent: - '- **Choose for calendar-based selection:** Use `DatePicker` when users benefit from seeing a calendar view, like selecting dates relative to today or needing weekday context. Use `DateSpinner` for tight spaces or `DateField` when users know the exact date.\n' + - '- **Provide adequate space:** Ensure sufficient spacing around the picker to avoid interfering with on-screen keyboards or other interactive elements.', - }, - { - type: 'Generic', - anchorLink: 'limitations', - title: 'Limitations', - sectionContent: - '- `DatePicker` provides the calendar interface but requires external state management for the selected value—you must update the `value` property in response to change events.\n' + - '- The component supports single dates, multiple dates, and date ranges through value format alone—the selection mode is inferred from the `value` property format rather than an explicit property.\n' + - "- Invalid date values result in no date being selected—the component doesn't provide specific error feedback, so you must validate date formats before setting the `value` property.", - }, - ], defaultExample: { image: 'date-picker-default.png', description: @@ -57,6 +40,17 @@ const data: ReferenceEntityTemplateSchema = { ], }, }, + subSections: [ + { + type: 'Generic', + anchorLink: 'best-practices', + title: 'Best practices', + sectionContent: ` +- **Choose for calendar-based selection:** Use \`DatePicker\` when users benefit from seeing a calendar view, like selecting dates relative to today or needing weekday context. Use [\`DateSpinner\`](/docs/api/pos-ui-extensions/2025-10/polaris-web-components/forms/datespinner) for tight spaces or [\`DateField\`](/docs/api/pos-ui-extensions/2025-10/polaris-web-components/forms/datefield) when users know the exact date. +- **Provide adequate space:** Ensure sufficient spacing around the picker to avoid interfering with on-screen keyboards or other interactive elements. +`, + }, + ], related: [], examples: { description: diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/DateSpinner/DateSpinner.doc.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/DateSpinner/DateSpinner.doc.ts index 14196bc6f4..0ba58e7530 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/DateSpinner/DateSpinner.doc.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/DateSpinner/DateSpinner.doc.ts @@ -4,7 +4,9 @@ const data: ReferenceEntityTemplateSchema = { name: 'DateSpinner', description: 'The `DateSpinner` component enables merchants to select a specific date using a spinner interface with scrollable columns for month, day, and year. Use it to provide compact date selection in constrained spaces.' + - '\n\n`DateSpinner` offers an alternative to calendar-style pickers when space is limited or when users prefer scrolling through date values. The spinner interface allows merchants to select dates by scrolling through separate columns for month, day, and year, providing a compact and intuitive way to select dates in constrained layouts.', + '\n\n`DateSpinner` uses ISO 8601 date format (`YYYY-MM-DD`) only. Other date formats require conversion before setting the value property.' + + '\n\n`DateSpinner` offers an alternative to [calendar-style pickers](/docs/api/pos-ui-extensions/2025-10/polaris-web-components/forms/datepicker) when space is limited or when users prefer scrolling through date values. The spinner interface allows merchants to select dates by scrolling through separate columns for month, day, and year, providing a compact and intuitive way to select dates in constrained layouts.' + + "\n\n`DateSpinner` doesn't include field labels, help text, or error messaging. Combine the component with other UI elements or text components to provide complete form field experiences.", thumbnail: 'date-spinner-thumbnail.png', isVisualComponent: true, type: '', @@ -24,26 +26,6 @@ const data: ReferenceEntityTemplateSchema = { ], category: 'Polaris web components', subCategory: 'Forms', - subSections: [ - { - type: 'Generic', - anchorLink: 'best-practices', - title: 'Best practices', - sectionContent: - '- **Use for space-constrained layouts:** Choose `DateSpinner` for narrow layouts or split-screen interfaces where a calendar view would be impractical.\n' + - '- **Best for nearby dates:** Use when selecting dates close to the current date. For distant dates, `DatePicker` provides faster navigation.\n' + - '- **Provide interaction cues:** Consider labels or instructions to help first-time users understand the scrollable column interface.', - }, - { - type: 'Generic', - anchorLink: 'limitations', - title: 'Limitations', - sectionContent: - '- `DateSpinner` uses [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date format (`YYYY-MM-DD`) only—other date formats require conversion before setting the value property.\n' + - '- The component provides spinner-based date selection exclusively—for calendar-style visual selection with month context, use the `DatePicker` component instead.\n' + - "- `DateSpinner` doesn't include field labels, help text, or error messaging—combine with other UI elements or text components to provide complete form field experiences.", - }, - ], defaultExample: { image: 'date-spinner-default.png', description: @@ -58,6 +40,18 @@ const data: ReferenceEntityTemplateSchema = { ], }, }, + subSections: [ + { + type: 'Generic', + anchorLink: 'best-practices', + title: 'Best practices', + sectionContent: ` +- **Use for space-constrained layouts:** Choose \`DateSpinner\` for narrow layouts or split-screen interfaces where a calendar view would be impractical. +- **Best for nearby dates:** Use when selecting dates close to the current date. For distant dates, [\`DatePicker\`](/docs/api/pos-ui-extensions/2025-10/polaris-web-components/forms/datepicker) provides faster navigation. +- **Provide interaction cues:** Consider labels or instructions to help first-time users understand the scrollable column interface. +`, + }, + ], related: [], examples: { description: diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/Divider/Divider.doc.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/Divider/Divider.doc.ts index 8011f07c85..973f844a27 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/Divider/Divider.doc.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/Divider/Divider.doc.ts @@ -5,7 +5,8 @@ const data: ReferenceEntityTemplateSchema = { description: 'The `Divider` component creates a visual separation between content sections. Use dividers to organize information and improve content hierarchy by providing clear section boundaries.' + '\n\nThe component renders a subtle horizontal line that follows design system specifications for color and thickness, maintaining visual consistency across the interface. It provides a clean way to separate content groups without adding significant visual weight, helping merchants scan and understand interface structure through strategic content segmentation.' + - '\n\n`Divider` components support both full-width and inset dividers with configurable margins, allowing precise control over visual separation without adding custom CSS for common divider placement patterns.', + "\n\nTo maintain consistency with the native POS styling, The component doesn't support custom styling beyond the available direction property. Other visual properties are controlled by the POS design system." + + "\n\n`Divider` components support both full-width and inset dividers with configurable margins, allowing precise control over visual separation without adding custom CSS for common divider placement patterns. Dividers don't automatically adjust spacing around themselves. Ensure your design uses appropriate margins and padding to achieve proper visual separation.", thumbnail: 'divider-thumbnail.png', isVisualComponent: true, type: '', @@ -19,25 +20,6 @@ const data: ReferenceEntityTemplateSchema = { ], category: 'Polaris web components', subCategory: 'Layout and structure', - subSections: [ - { - type: 'Generic', - anchorLink: 'best-practices', - title: 'Best practices', - sectionContent: - '- **Choose appropriate direction:** Use `inline` (horizontal) for most content separation. Use `block` (vertical) for columns or sidebar boundaries.\n' + - '- **Avoid overuse:** Use dividers strategically. In dense interfaces, consider whitespace or typography hierarchy instead.', - }, - { - type: 'Generic', - anchorLink: 'limitations', - title: 'Limitations', - sectionContent: - "- `Divider` is a purely visual component and doesn't provide interactive functionality—it serves only to create visual separation between content areas.\n" + - "- The component doesn't support custom styling beyond the available direction property—color, thickness, and other visual properties are controlled by the POS design system.\n" + - "- Dividers don't automatically adjust spacing around themselves—you must manage appropriate margins and padding in surrounding content to achieve proper visual separation.", - }, - ], defaultExample: { image: 'divider-default.png', description: @@ -52,6 +34,17 @@ const data: ReferenceEntityTemplateSchema = { ], }, }, + subSections: [ + { + type: 'Generic', + anchorLink: 'best-practices', + title: 'Best practices', + sectionContent: ` +- **Choose appropriate direction:** Use \`inline\` (horizontal) for most content separation. Use \`block\` (vertical) for columns or sidebar boundaries. +- **Avoid overuse:** Use dividers strategically. In dense interfaces, consider whitespace or typography hierarchy instead. +`, + }, + ], related: [], }; diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/EmailField/EmailField.doc.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/EmailField/EmailField.doc.ts index a6f445e193..e002f454d1 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/EmailField/EmailField.doc.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/EmailField/EmailField.doc.ts @@ -3,8 +3,8 @@ import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs'; const data: ReferenceEntityTemplateSchema = { name: 'EmailField', description: - 'The `EmailField` component captures email address input from customers with built-in validation. Use it to collect email information in forms, customer profiles, or contact workflows.' + - '\n\nThe component includes built-in email format validation using standard email patterns to ensure data quality. It provides real-time feedback on invalid entries and supports features like autocomplete and keyboard optimization for email input, helping merchants quickly capture valid customer contact information during checkout or registration workflows.' + + 'The `EmailField` component captures email address input from customers. Use it to collect email information in forms, customer profiles, or contact workflows.' + + "\n\n`EmailField` provides the input interface but doesn't perform automatic email validation. Implement your own validation logic, and use the `error` property to display validation results." + '\n\n`EmailField` components integrate with browser autocomplete features to speed up email entry by suggesting previously used addresses, significantly reducing typing time during customer registration workflows.', thumbnail: 'email-field-thumbnail.png', isVisualComponent: true, @@ -31,26 +31,6 @@ const data: ReferenceEntityTemplateSchema = { ], category: 'Polaris web components', subCategory: 'Forms', - subSections: [ - { - type: 'Generic', - anchorLink: 'best-practices', - title: 'Best practices', - sectionContent: - '- **Write descriptive labels:** Use specific labels like "Customer Email" or "Receipt Email Address" rather than generic "Email."\n' + - '- **Provide context in details:** Use `details` for additional context like "Required for digital receipts" or "We\'ll send order updates to this address."\n' + - '- **Write actionable error messages:** Provide clear validation messages like "Please enter a valid email address" that help users correct their input.', - }, - { - type: 'Generic', - anchorLink: 'limitations', - title: 'Limitations', - sectionContent: - "- `EmailField` provides the input interface but doesn't perform automatic email validation—you must implement validation logic and use the `error` property to display validation results.\n" + - "- The `required` property adds semantic meaning only—it doesn't trigger automatic error display, so you must manually check for empty values and set errors accordingly.\n" + - "- The `accessory` slot supports only `Button` and `Clickable` components—other component types can't be used in the accessory slot.", - }, - ], defaultExample: { image: 'email-field-default.png', description: @@ -65,6 +45,26 @@ const data: ReferenceEntityTemplateSchema = { ], }, }, + subSections: [ + { + type: 'Generic', + anchorLink: 'best-practices', + title: 'Best practices', + sectionContent: ` +- **Write descriptive labels:** Use specific labels like "Customer Email" or "Receipt Email Address" rather than generic "Email." +- **Provide context in details:** Use \`details\` for additional context like "Required for digital receipts" or "We'll send order updates to this address." +- **Write actionable error messages:** Provide clear validation messages like "Please enter a valid email address" that help users correct their input. +`, + }, + { + type: 'Generic', + anchorLink: 'limitations', + title: 'Limitations', + sectionContent: ` +The \`accessory\` slot supports only [\`Button\`](/docs/api/pos-ui-extensions/2025-10/polaris-web-components/actions/button) and [\`Clickable\`](/docs/api/pos-ui-extensions/2025-10/polaris-web-components/actions/clickable) components—other component types can't be used in the accessory slot. +`, + }, + ], related: [], examples: { description: @@ -72,7 +72,7 @@ const data: ReferenceEntityTemplateSchema = { examples: [ { description: - 'Add action buttons to the email field using the accessory slot for quick actions like clearing input or verifying email addresses. This example shows how to use `s-button` and `s-clickable` components in the accessory slot, providing inline functionality within the email input context.', + 'Add action buttons to the email field using the accessory slot for quick actions like clearing input or verifying email addresses. This example shows how to use [`s-button`](/docs/api/pos-ui-extensions/2025-10/polaris-web-components/actions/button) and [`s-clickable`](/docs/api/pos-ui-extensions/2025-10/polaris-web-components/actions/clickable) components in the accessory slot, providing inline functionality within the email input context.', codeblock: { title: 'Add accessory buttons', tabs: [ diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/Heading/Heading.doc.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/Heading/Heading.doc.ts index 181a808dbd..b07a415e7a 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/Heading/Heading.doc.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/Heading/Heading.doc.ts @@ -3,9 +3,8 @@ import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs'; const data: ReferenceEntityTemplateSchema = { name: 'Heading', description: - 'The `Heading` component renders hierarchical titles to communicate the structure and organization of page content. Heading levels adjust automatically based on nesting within parent Section components, ensuring a meaningful page outline.' + - '\n\nUse headings to create clear information hierarchy and help users navigate complex interfaces efficiently.' + - '\n\n`Heading` components provide consistent typographic scaling that maintains visual hierarchy while ensuring headings remain readable at all levels, even when deeply nested within multiple `Section` components.', + "The `Heading` component renders hierarchical titles to communicate the structure and organization of page content and help users navigate complex interfaces. Heading levels adjust automatically based on nesting within parent [`Section`](/docs/api/pos-ui-extensions/2025-10/polaris-web-components/layout-and-structure/section) components, ensuring a meaningful page outline. Use plain text or simple inline elements only for heading content; rich text format isn't supported." + + '\n\nThe styling of `Heading` components is controlled by the POS design system. This provides consistent typographic scaling that maintains visual hierarchy while ensuring headings remain readable at all levels, even when deeply nested within multiple [`Section`](/docs/api/pos-ui-extensions/2025-10/polaris-web-components/layout-and-structure/section) components. ', thumbnail: 'heading-thumbnail.png', isVisualComponent: true, type: '', @@ -19,26 +18,6 @@ const data: ReferenceEntityTemplateSchema = { ], category: 'Polaris web components', subCategory: 'Layout and structure', - subSections: [ - { - type: 'Generic', - anchorLink: 'best-practices', - title: 'Best practices', - sectionContent: - '- **Create logical hierarchy:** Start with higher-level headings for main sections, nested headings for subsections. Nested sections automatically adjust heading levels.\n' + - '- **Write specific headings:** Avoid generic terms like "Details." Use specific descriptions like "Customer Contact Information" or "Transaction Summary."\n' + - "- **Keep text concise:** Headings don't truncate, so keep them brief enough to display across different screen sizes.", - }, - { - type: 'Generic', - anchorLink: 'limitations', - title: 'Limitations', - sectionContent: - '- Heading levels are automatically determined by nesting within `Section` components—manual heading level control is not available to ensure consistent document structure.\n' + - "- The component doesn't support rich text formatting within the heading content—use plain text or simple inline elements for heading content.\n" + - "- Visual styling is controlled by the POS design system and heading level—custom typography styles beyond the available properties aren't supported.", - }, - ], defaultExample: { image: 'heading-default.png', description: @@ -53,6 +32,18 @@ const data: ReferenceEntityTemplateSchema = { ], }, }, + subSections: [ + { + type: 'Generic', + anchorLink: 'best-practices', + title: 'Best practices', + sectionContent: ` +- **Create logical hierarchy:** Start with higher-level headings for main sections, nested headings for subsections. Nested sections automatically adjust heading levels. +- **Write specific headings:** Avoid generic terms like "Details." Use specific descriptions like "Customer Contact Information" or "Transaction Summary." +- **Keep text concise:** Headings don't truncate, so keep them brief enough to display across different screen sizes. +`, + }, + ], related: [], }; diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/Icon/Icon.doc.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/Icon/Icon.doc.ts index 3e015dca1f..07865f1ac5 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/Icon/Icon.doc.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/Icon/Icon.doc.ts @@ -4,7 +4,8 @@ const data: ReferenceEntityTemplateSchema = { name: 'Icon', description: 'The `Icon` component displays standardized visual symbols from the POS catalog to represent actions, statuses, or categories consistently. Use icons to enhance navigation or provide visual context alongside text in POS interfaces.' + - '\n\nIcons help merchants quickly understand interface elements and actions without relying solely on text labels. Icons are optimized for readability at standard sizes and automatically scale to maintain visual consistency across different screen densities and device types.', + "\n\n To use icons to create interactive UI elements, wrap them in [`Button`](/docs/api/pos-ui-extensions/2025-10/polaris-web-components/actions/button) or [`Clickable`](/docs/api/pos-ui-extensions/2025-10/polaris-web-components/actions/clickable) components. Icons on their behave purely as images and don't support click events or interactive behaviors." + + "\n\n To maintain a consistent visual apperance, icon styling is controlled by the POS design system. Custom styling and external icon libraries aren't supported. Icons are optimized for readability at standard sizes and automatically scale to maintain visual consistency across different screen densities and device types.", thumbnail: 'icon-thumbnail.png', isVisualComponent: true, type: '', @@ -18,28 +19,6 @@ const data: ReferenceEntityTemplateSchema = { ], category: 'Polaris web components', subCategory: 'Media and visuals', - subSections: [ - { - type: 'Generic', - anchorLink: 'best-practices', - title: 'Best practices', - sectionContent: - '- **Choose recognizable icons:** Use universally recognized symbols like `search`, `cart`, or `settings`. Avoid ambiguous icons.\n' + - '- **Match size to context:** Use smaller sizes for inline text or secondary actions, `base` for standard elements, larger sizes for primary actions.\n' + - '- **Apply tones for meaning:** Use `critical` for destructive actions, `warning` for cautions, `success` for confirmations, `auto` or `neutral` for general elements.\n' + - '- **Pair with text for clarity:** Consider adding text labels, especially for complex or uncommon actions.\n' + - '- **Use color for hierarchy:** Use `subdued` for secondary elements, `base` for standard visibility, `strong` for emphasis.', - }, - { - type: 'Generic', - anchorLink: 'limitations', - title: 'Limitations', - sectionContent: - "- Icons are purely decorative and don't support click events or interactive behaviors—wrap them in `Clickable` components for interactive functionality.\n" + - "- The available icon set is predefined and limited to POS-specific symbols—custom icons or external icon libraries aren't supported.\n" + - '- Icon appearance and styling are controlled by the POS design system—custom colors, styles, or modifications beyond the provided properties are not available.', - }, - ], defaultExample: { image: 'icon-default.png', description: @@ -54,6 +33,20 @@ const data: ReferenceEntityTemplateSchema = { ], }, }, + subSections: [ + { + type: 'Generic', + anchorLink: 'best-practices', + title: 'Best practices', + sectionContent: ` +- **Choose recognizable icons:** Use universally recognized symbols like \`search\`, \`cart\`, or \`settings\`. Avoid ambiguous icons. +- **Match size to context:** Use smaller sizes for inline text or secondary actions, \`base\` for standard elements, larger sizes for primary actions. +- **Apply tones for meaning:** Use \`critical\` for destructive actions, \`warning\` for cautions, \`success\` for confirmations, \`auto\` or \`neutral\` for general elements. +- **Pair with text for clarity:** Consider adding text labels, especially for complex or uncommon actions. +- **Use color for hierarchy:** Use \`subdued\` for secondary elements, \`base\` for standard visibility, \`strong\` for emphasis. +`, + }, + ], related: [], }; diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/Image/Image.doc.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/Image/Image.doc.ts index da145f216f..5c69489cef 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/Image/Image.doc.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/Image/Image.doc.ts @@ -3,7 +3,7 @@ import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs'; const data: ReferenceEntityTemplateSchema = { name: 'Image', description: - 'The `Image` component adds visual content to the POS interface and allows you to customize the presentation of visuals. Use images to showcase products, illustrate concepts, provide visual context, or support user tasks and interactions in POS workflows.' + + 'The `Image` component adds visual content to the POS interface and allows you to customize the presentation of visuals. Use images to showcase products, illustrate concepts, provide visual context, or support user tasks and interactions in POS workflows. Images are display-only components. For interactive functionality, wrap them in [`Button`](/docs/api/pos-ui-extensions/2025-10/polaris-web-components/actions/button) or [`Clickable`](/docs/api/pos-ui-extensions/2025-10/polaris-web-components/actions/clickable) components.' + '\n\nImages enhance the user experience by providing immediate visual recognition and reducing cognitive load.' + '\n\n`Image` components handle loading errors gracefully with fallback options and provides placeholder states to maintain layout stability during image loading on slower network connections. The component implements lazy loading for images outside the viewport, improving initial page load performance while ensuring smooth scrolling as merchants navigate through product catalogs or image-heavy interfaces.', thumbnail: 'image-thumbnail.png', @@ -19,25 +19,6 @@ const data: ReferenceEntityTemplateSchema = { ], category: 'Polaris web components', subCategory: 'Media and visuals', - subSections: [ - { - type: 'Generic', - anchorLink: 'best-practices', - title: 'Best practices', - sectionContent: - '- **Choose appropriate sizing:** Use `inlineSize="fill"` for responsive layouts. Use `inlineSize="auto"` to maintain natural dimensions.\n' + - '- **Select object fit behavior:** Use `objectFit="contain"` to show the complete image. Use `objectFit="cover"` to fill the container, accepting cropping.', - }, - { - type: 'Generic', - anchorLink: 'limitations', - title: 'Limitations', - sectionContent: - "- Images are display-only components and don't support click events or interactive behaviors—wrap them in `Clickable` components for interactive functionality.\n" + - '- Image loading and caching behavior depends on the browser and network conditions—implement proper error handling and loading states for better user experience.\n' + - '- Large images can impact performance—ensure proper optimization and compression for better loading times.', - }, - ], defaultExample: { image: 'image-default.png', description: @@ -52,6 +33,26 @@ const data: ReferenceEntityTemplateSchema = { ], }, }, + subSections: [ + { + type: 'Generic', + anchorLink: 'best-practices', + title: 'Best practices', + sectionContent: ` +- **Choose appropriate sizing:** Use \`inlineSize="fill"\` for responsive layouts. Use \`inlineSize="auto"\` to maintain natural dimensions. +- **Select object fit behavior:** Use \`objectFit="contain"\` to show the complete image. Use \`objectFit="cover"\` to fill the container, accepting cropping. +- **Implement error handling and loading states:** Image loading and caching behavior depends on the browser and network conditions—implement proper error handling and loading states for better user experience. +`, + }, + { + type: 'Generic', + anchorLink: 'limitations', + title: 'Limitations', + sectionContent: ` +Large images can impact performance—ensure proper optimization and compression for better loading times. +`, + }, + ], related: [], }; diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/Modal/Modal.doc.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/Modal/Modal.doc.ts index 685e484b9f..fd3f2b054c 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/Modal/Modal.doc.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/Modal/Modal.doc.ts @@ -4,7 +4,8 @@ const data: ReferenceEntityTemplateSchema = { name: 'Modal', description: 'The `Modal` component displays content in an overlay that requires merchant attention. Use modals to present critical information, confirmations, or focused tasks while maintaining page context.' + - '\n\nModals block interaction with the underlying interface until the merchant resolves the modal content. The component maintains focus within the modal boundary and returns focus to the trigger element on close, ensuring keyboard navigation remains predictable throughout the modal lifecycle.', + '\n\nModals block interaction with the underlying interface until the merchant resolves the modal content. The component maintains focus within the modal boundary and returns focus to the trigger element on close, ensuring keyboard navigation remains predictable throughout the modal lifecycle.' + + "\n\nModals don't automatically handle state management or persistence, so manage visibility and lifecycle programmatically through events and commands.", thumbnail: 'modal-thumbnail.png', isVisualComponent: true, type: '', @@ -30,27 +31,6 @@ const data: ReferenceEntityTemplateSchema = { ], category: 'Polaris web components', subCategory: 'Feedback and status indicators', - subSections: [ - { - type: 'Generic', - anchorLink: 'best-practices', - title: 'Best practices', - sectionContent: - '- **Use for focused interactions:** Reserve modals for confirmations, critical information, or tasks requiring immediate attention.\n' + - '- **Write clear headings:** Use concise titles that communicate the purpose or action.\n' + - "- **Choose appropriate button tones:** The `primary-action` button's `tone` determines the modal's overall tone. Use `critical` for destructive actions, `success` for confirmations.\n" + - '- **Include secondary actions:** Provide options like "Cancel" or "Go Back" to give merchants flexibility.\n' + - '- **Keep content focused:** Limit to essential information and actions. For complex workflows, break into multiple steps.', - }, - { - type: 'Generic', - anchorLink: 'limitations', - title: 'Limitations', - sectionContent: - "- Multiple modals can't be displayed simultaneously—showing a new modal while another is visible may cause unexpected behavior or poor user experience.\n" + - "- Modal visibility and lifecycle must be managed programmatically through events and commands—they don't automatically handle state management or persistence.", - }, - ], defaultExample: { image: 'modal-default.png', description: @@ -65,6 +45,28 @@ const data: ReferenceEntityTemplateSchema = { ], }, }, + subSections: [ + { + type: 'Generic', + anchorLink: 'best-practices', + title: 'Best practices', + sectionContent: ` +- **Use for focused interactions:** Reserve modals for confirmations, critical information, or tasks requiring immediate attention. +- **Write clear headings:** Use concise titles that communicate the purpose or action. +- **Choose appropriate button tones:** The primary-action button's \`tone\` determines the modal's overall tone. Use \`critical\` for destructive actions, \`success\` for confirmations. +- **Include secondary actions:** Provide options like "Cancel" or "Go Back" to give merchants flexibility. +- **Keep content focused:** Limit to essential information and actions. For complex workflows, break into multiple steps. +`, + }, + { + type: 'Generic', + anchorLink: 'limitations', + title: 'Limitations', + sectionContent: ` +Multiple modals can't be displayed simultaneously—showing a new modal while another is visible may cause unexpected behavior or poor user experience. +`, + }, + ], related: [], }; diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/NumberField/NumberField.doc.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/NumberField/NumberField.doc.ts index 3200f519e5..e8e04e5ba9 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/NumberField/NumberField.doc.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/NumberField/NumberField.doc.ts @@ -3,7 +3,7 @@ import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs'; const data: ReferenceEntityTemplateSchema = { name: 'NumberField', description: - 'The `NumberField` component captures numeric input with built-in validation. Use it to collect quantity, price, or other numeric information with optional `stepper` controls.' + + "The `NumberField` component captures numeric input. Use it to collect quantity, price, or other numeric information with optional `stepper` control. Stepper controls restrict which properties are available—`label`, `details`, `placeholder`, `error`, `required`, and `inputMode` aren't supported. Choose your control type based on which properties your implementation requires." + '\n\nThe component includes built-in number validation, optional min/max constraints, and step increments to ensure accurate numeric data entry. It supports various number formats including integers and decimals, with validation feedback to prevent entry errors during high-volume retail operations.', thumbnail: 'number-field-thumbnail.png', isVisualComponent: true, @@ -30,26 +30,6 @@ const data: ReferenceEntityTemplateSchema = { ], category: 'Polaris web components', subCategory: 'Forms', - subSections: [ - { - type: 'Generic', - anchorLink: 'best-practices', - title: 'Best practices', - sectionContent: - '- **Choose appropriate controls:** Use `stepper` for quantities or small adjustments. Use `none` for prices or large values where steppers are impractical.\n' + - '- **Select the right input mode:** Use `decimal` for prices and measurements. Use `numeric` for quantities and counts.\n' + - '- **Explain constraints in details:** Use `details` to clarify valid ranges or formatting, like "Enter a quantity between 1 and 999."', - }, - { - type: 'Generic', - anchorLink: 'limitations', - title: 'Limitations', - sectionContent: - "- `NumberField` provides numeric input but doesn't enforce `min`/`max` constraints for keyboard input—you must implement validation logic to enforce bounds and display appropriate errors.\n" + - '- The component handles numeric input and basic format validation, but specialized number formatting like currency symbols or thousand separators requires additional formatting logic.\n' + - '- Stepper controls work best for small ranges and adjustments—they may not be practical for large numeric ranges or precise decimal entry.', - }, - ], defaultExample: { image: 'number-field-default.png', description: @@ -64,6 +44,18 @@ const data: ReferenceEntityTemplateSchema = { ], }, }, + subSections: [ + { + type: 'Generic', + anchorLink: 'best-practices', + title: 'Best practices', + sectionContent: ` +- **Choose appropriate controls:** Use \`stepper\` for quantities or small adjustments. Use \`none\` for prices or large values where steppers are impractical. +- **Select the right input mode:** Use \`decimal\` for prices and measurements. Use \`numeric\` for quantities and counts. +- **Explain constraints in details:** Use \`details\` to clarify valid ranges or formatting, like "Enter a quantity between 1 and 999." +`, + }, + ], related: [], examples: { description: diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/Page/Page.doc.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/Page/Page.doc.ts index 28a881b803..366984e8d2 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/Page/Page.doc.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/Page/Page.doc.ts @@ -3,8 +3,8 @@ import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs'; const data: ReferenceEntityTemplateSchema = { name: 'Page', description: - 'The `Page` component serves as the main container for app content with preset layouts and heading controls. Use it to structure full-screen views with consistent navigation and content organization.' + - '\n\nThe component provides a complete page structure with built-in header, sidebar, and action bar layouts that follow POS design patterns. It manages heading hierarchy, spacing, and responsive behavior automatically, allowing you to focus on content rather than layout mechanics while ensuring consistent page structures across extensions.' + + "The `Page` component serves as the main container for app content with preset layouts and heading controls. Use it to structure full-screen views with consistent navigation and content organization. `Page` is designed for full-screen modal interfaces and isn't suitable for inline content or partial page layouts within existing POS screens." + + '\n\nThe component provides a complete page structure with built-in header, sidebar, and action bar layouts that follow POS design patterns. It manages heading hierarchy, spacing, and responsive behavior automatically, allowing you to focus on content rather than layout mechanics while ensuring consistent page structures across extensions. To maintain consistency, page layout and styling are controlled by the POS design system, so custom styling is limited to the provided slots and properties.' + '\n\n`Page` components handle safe area insets automatically for devices with notches or rounded corners, ensuring content remains visible and interactive without manual padding adjustments for different device shapes.', thumbnail: 'page-thumbnail.png', isVisualComponent: true, @@ -25,26 +25,6 @@ const data: ReferenceEntityTemplateSchema = { ], category: 'Polaris web components', subCategory: 'Layout and structure', - subSections: [ - { - type: 'Generic', - anchorLink: 'best-practices', - title: 'Best practices', - sectionContent: - "- **Write descriptive headings:** Use heading and subheading to describe the page's purpose and provide context about the current workflow step.\n" + - "- **Place one primary action in action bar:** Use the `secondary-actions` slot for the page's most important action.\n" + - '- **Use aside for supplementary content:** Reserve the aside slot for navigation, contextual help, or supporting information.', - }, - { - type: 'Generic', - anchorLink: 'limitations', - title: 'Limitations', - sectionContent: - "- The `secondary-actions` slot supports only a single button element—multiple actions in the action bar aren't supported and should be handled within the main content area.\n" + - '- Page layout and styling are controlled by the POS design system—custom page-level styling beyond the provided slots and properties is not available.\n' + - "- The component is designed for full-screen modal interfaces—it's not suitable for inline content or partial page layouts within existing POS screens.", - }, - ], defaultExample: { image: 'page-default.png', description: @@ -59,6 +39,26 @@ const data: ReferenceEntityTemplateSchema = { ], }, }, + subSections: [ + { + type: 'Generic', + anchorLink: 'best-practices', + title: 'Best practices', + sectionContent: ` +- **Write descriptive headings:** Use heading and subheading to describe the page's purpose and provide context about the current workflow step. +- **Place one primary action in action bar:** Use the secondary-actions slot for the page's most important action. +- **Use aside for supplementary content:** Reserve the aside slot for navigation, contextual help, or supporting information. +`, + }, + { + type: 'Generic', + anchorLink: 'limitations', + title: 'Limitations', + sectionContent: ` +The secondary-actions slot supports only a single button element. Multiple actions in the action bar aren't supported and should be handled within the main content area. +`, + }, + ], related: [], }; diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/PosBlock/PosBlock.doc.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/PosBlock/PosBlock.doc.ts index 0839acff01..2dacc50309 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/PosBlock/PosBlock.doc.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/PosBlock/PosBlock.doc.ts @@ -4,7 +4,7 @@ const data: ReferenceEntityTemplateSchema = { name: 'PosBlock', description: 'The `PosBlock` component creates a container to place content with an action button. Use it to display structured content within POS block targets.' + - '\n\nThe component provides a standardized layout specifically designed for content blocks within POS detail views, with consistent padding, spacing, and optional action buttons. It integrates with the native POS design language, ensuring extension content feels cohesive with the core POS interface while maintaining clear content boundaries.' + + "\n\nThe component provides a standardized layout specifically designed for content blocks within POS detail views, with consistent padding, spacing, and optional action buttons. It integrates with the native POS design language, ensuring extension content feels cohesive with the core POS interface while maintaining clear content boundaries. Custom styling beyond content organization isn't supported." + '\n\n`PosBlock` components provide consistent interaction patterns for action buttons across different block types, ensuring merchants can predict button behavior and location regardless of the specific POS context.', thumbnail: 'pos-block-thumbnail.png', isVisualComponent: true, @@ -31,25 +31,6 @@ const data: ReferenceEntityTemplateSchema = { ], category: 'Polaris web components', subCategory: 'Layout and structure', - subSections: [ - { - type: 'Generic', - anchorLink: 'best-practices', - title: 'Best practices', - sectionContent: - "- **Provide descriptive headings:** If you don't specify a heading, the system uses your extension's description, so ensure it's meaningful and concise.\n" + - "- **Place important actions in secondary-actions slot:** Include only the most relevant actions directly related to your block's content.", - }, - { - type: 'Generic', - anchorLink: 'limitations', - title: 'Limitations', - sectionContent: - "- `PosBlock` is designed specifically for block targets—it can't be used in modal or action (menu item) targets.\n" + - "- The component's visual styling is controlled by the POS design system—custom styling beyond content organization isn't supported.\n" + - "- Only one secondary action element is recommended to maintain clean, focused interfaces that don't overwhelm the existing POS workflow.", - }, - ], defaultExample: { image: 'pos-block-default.png', description: @@ -64,6 +45,18 @@ const data: ReferenceEntityTemplateSchema = { ], }, }, + subSections: [ + { + type: 'Generic', + anchorLink: 'best-practices', + title: 'Best practices', + sectionContent: ` +- **Provide descriptive headings:** If you don't specify a heading, the system uses your extension's description, so ensure it's meaningful and concise. +- **Place important actions in secondary-actions slot:** Include only the most relevant actions directly related to your block's content. +- **Limit secondary actions:** To maintain clean, focused interfaces that don't overwhelm the existing POS workflow, use only one secondary action element in each block. +`, + }, + ], related: [], }; diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/ScrollBox/ScrollBox.doc.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/ScrollBox/ScrollBox.doc.ts index 57c972dde6..8a3c4420e6 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/ScrollBox/ScrollBox.doc.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/ScrollBox/ScrollBox.doc.ts @@ -19,25 +19,6 @@ const data: ReferenceEntityTemplateSchema = { ], category: 'Polaris web components', subCategory: 'Layout and structure', - subSections: [ - { - type: 'Generic', - anchorLink: 'best-practices', - title: 'Best practices', - sectionContent: - '- **Set clear dimensions:** Use percentage values for responsive layouts or pixels for exact dimensions.\n' + - '- **Use for appropriate content:** Reserve `ScrollBox` for long lists or dynamic content that genuinely needs scrolling, not short content that fits within available space.', - }, - { - type: 'Generic', - anchorLink: 'limitations', - title: 'Limitations', - sectionContent: - "- `ScrollBox` automatically manage overflow behavior—manual overflow control beyond the component's built-in scrolling isn't available.\n" + - "- Scroll behavior and styling are controlled by the POS design system—custom scroll bar styling or scroll physics modifications aren't supported.\n" + - '- The component is optimized for touch-based scrolling in POS environments—complex scroll interactions or nested scrolling scenarios may not perform optimally.', - }, - ], defaultExample: { image: 'scrollbox-default.png', description: @@ -52,6 +33,17 @@ const data: ReferenceEntityTemplateSchema = { ], }, }, + subSections: [ + { + type: 'Generic', + anchorLink: 'best-practices', + title: 'Best practices', + sectionContent: ` +- **Set clear dimensions:** Use percentage values for responsive layouts or pixels for exact dimensions. +- **Use for appropriate content:** Reserve \`ScrollBox\` for long lists or dynamic content that genuinely needs scrolling, not short content that fits within available space. +`, + }, + ], related: [], }; diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/SearchField/SearchField.doc.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/SearchField/SearchField.doc.ts index 6951218eae..e9e4447742 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/SearchField/SearchField.doc.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/SearchField/SearchField.doc.ts @@ -5,7 +5,8 @@ const data: ReferenceEntityTemplateSchema = { description: 'The `SearchField` component captures search terms using a single-line input field. Use it to enable search and filtering within POS interfaces.' + '\n\nThe component includes built-in debouncing to optimize performance during real-time search operations and supports features like autocomplete suggestions and search history. It provides clear visual feedback for search states including loading, results found, and no results, helping merchants quickly locate products, customers, or orders in large catalogs.' + - '\n\n`SearchField` components clear search queries with a single tap on the clear button while maintaining search history for quick access to recent searches, balancing convenience with data management.', + '\n\n`SearchField` components clear search queries with a single tap on the clear button while maintaining search history for quick access to recent searches, balancing convenience with data management.' + + '\n\n`SearchField` is optimized for inline search and filtering. For additional search features like sorting and search history use a custom implementation.', thumbnail: 'search-field-thumbnail.png', isVisualComponent: true, type: '', @@ -25,27 +26,6 @@ const data: ReferenceEntityTemplateSchema = { ], category: 'Polaris web components', subCategory: 'Forms', - subSections: [ - { - type: 'Generic', - anchorLink: 'best-practices', - title: 'Best practices', - sectionContent: - '- **Use for inline search and filtering:** Choose `SearchField` for filtering within specific sections or lists, not for global navigation or complex multi-step searches.\n' + - '- **Follow placeholder pattern:** Use "Search {items}" format like "Search products" or "Search customers" to clarify scope.\n' + - '- **Choose the right event:** Use `input` for real-time filtering as users type. Use `change` for expensive operations that should wait until typing completes.\n' + - '- **Handle empty values:** When the field is cleared, reset filters or show all items appropriately.', - }, - { - type: 'Generic', - anchorLink: 'limitations', - title: 'Limitations', - sectionContent: - '- `SearchField` provides a search input field with visual styling and clear functionality—additional search features like filters, sorting, search history, or search buttons require custom implementation.\n' + - '- The component handles text input and basic interaction events—complex search workflows with multiple steps or advanced state management require additional components or custom logic.\n' + - '- `SearchField` is optimized for inline search and filtering—displaying search results requires using other components like `Stack`, `Section`, or custom layout components to present filtered content.', - }, - ], defaultExample: { image: 'search-field-default.png', description: @@ -60,6 +40,19 @@ const data: ReferenceEntityTemplateSchema = { ], }, }, + subSections: [ + { + type: 'Generic', + anchorLink: 'best-practices', + title: 'Best practices', + sectionContent: ` +- **Use for inline search and filtering:** Choose \`SearchField\` for filtering within specific sections or lists, not for global navigation or complex multi-step searches. +- **Follow placeholder pattern:** Use "Search {items}" format like "Search products" or "Search customers" to clarify scope. +- **Choose the right event:** Use \`input\` for real-time filtering as users type. Use \`change\` for expensive operations that should wait until typing completes. +- **Handle empty values:** When the field is cleared, reset filters or show all items appropriately. +`, + }, + ], related: [], examples: { description: diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/Section/Section.doc.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/Section/Section.doc.ts index 8a90f072d4..38e609a3f5 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/Section/Section.doc.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/Section/Section.doc.ts @@ -4,7 +4,8 @@ const data: ReferenceEntityTemplateSchema = { name: 'Section', description: 'The `Section` component groups related content into clearly-defined thematic areas. Sections have contextual heading levels to maintain a meaningful page structure.' + - '\n\nUse sections to organize content logically and provide clear navigation landmarks. The component manages heading levels to ensure nested sections maintain proper semantic structure.', + '\n\nUse sections to organize content logically and provide clear navigation landmarks. The component manages heading levels automatically to ensure nested sections maintain proper semantic structure.' + + "\n\nTo maintain clean, focused interfaces that don't overwhelm users, only one secondary action button is supported for each section.", thumbnail: 'section-thumbnail.png', isVisualComponent: true, type: '', @@ -24,26 +25,6 @@ const data: ReferenceEntityTemplateSchema = { ], category: 'Polaris web components', subCategory: 'Layout and structure', - subSections: [ - { - type: 'Generic', - anchorLink: 'best-practices', - title: 'Best practices', - sectionContent: - "- **Write descriptive headings:** Provide clear heading text that represents the section's content.\n" + - '- **Let heading levels adjust automatically:** Nested sections automatically adjust heading levels for proper semantic structure.\n' + - '- **Place relevant secondary actions:** Use the `secondary-actions` slot for actions that apply to the entire section, like "Edit Settings" or "Add Item."', - }, - { - type: 'Generic', - anchorLink: 'limitations', - title: 'Limitations', - sectionContent: - '- Section heading levels are automatically determined by nesting depth—manual heading level control is not available to ensure consistent document structure.\n' + - "- Only one secondary action button is supported per section to maintain clean, focused interfaces that don't overwhelm users.\n" + - "- The component's visual styling and spacing are controlled by the POS design system—custom section styling beyond content organization is not supported.", - }, - ], defaultExample: { image: 'section-default.png', description: @@ -58,6 +39,18 @@ const data: ReferenceEntityTemplateSchema = { ], }, }, + subSections: [ + { + type: 'Generic', + anchorLink: 'best-practices', + title: 'Best practices', + sectionContent: ` +- **Write descriptive headings:** Provide clear heading text that represents the section's content. +- **Let heading levels adjust automatically:** Nested sections automatically adjust heading levels for proper semantic structure. +- **Place relevant secondary actions:** Use the secondary-actions slot for actions that apply to the entire section, like "Edit Settings" or "Add Item." +`, + }, + ], related: [], }; diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/Stack/Stack.doc.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/Stack/Stack.doc.ts index abfd8319f4..5753d86ab6 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/Stack/Stack.doc.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/Stack/Stack.doc.ts @@ -5,7 +5,8 @@ const data: ReferenceEntityTemplateSchema = { description: 'The `Stack` component organizes elements horizontally or vertically along the block or inline axis. Use it to structure layouts, group related components, or control spacing between elements with flexible alignment options.' + '\n\nThe component simplifies layout creation by automatically managing spacing between child elements through gap properties, eliminating the need for manual margin management. It supports both horizontal and vertical arrangements, flexible alignment options, and wrapping behavior, making it the foundation for building consistent, responsive layouts throughout POS extensions.' + - '\n\n`Stack` components support responsive gap values that automatically adjust spacing based on screen size, ensuring layouts remain visually balanced and maintain proper element separation across different devices.', + "\n\nThe spacing of `Stack` components' gap values automatically adjust based on screen size. This ensures layouts remain visually balanced and maintain proper element separation across different devices." + + '\n\nComplex grid-like layouts may require multiple nested `Stack` components or alternative layout approaches for optimal results.', thumbnail: 'stack-thumbnail.png', isVisualComponent: true, type: '', @@ -19,28 +20,6 @@ const data: ReferenceEntityTemplateSchema = { ], category: 'Polaris web components', subCategory: 'Layout and structure', - subSections: [ - { - type: 'Generic', - anchorLink: 'best-practices', - title: 'Best practices', - sectionContent: - "- **Choose appropriate direction:** Use `block` for vertical arrangements like forms. Use `inline` for horizontal arrangements like button groups. Note that inline wraps while block doesn't.\n" + - '- **Use design system spacing:** Use `SpacingKeyword` values for consistency. Start with `base` and adjust as needed.\n' + - '- **Apply alignment properties:** Use `justifyContent` for main axis distribution, `alignItems` for cross axis positioning, `alignContent` for extra space distribution.\n' + - "- **Avoid percentages on mobile:** Don't use percentage-based sizing within scrollable containers on mobile surfaces.\n" + - '- **Use gap for spacing control:** Use `gap` for uniform spacing, `rowGap` for block axis, `columnGap` for inline axis.', - }, - { - type: 'Generic', - anchorLink: 'limitations', - title: 'Limitations', - sectionContent: - "- Wrapping behavior is determined by direction—inline stacks wrap content while block stacks don't, which may not suit all layout requirements.\n" + - '- Percentage-based sizing should be avoided on mobile surfaces within scrollable containers due to unexpected behavior.\n' + - '- Complex grid-like layouts may require multiple nested `Stack` components or alternative layout approaches for optimal results.', - }, - ], defaultExample: { image: 'stack-default.png', description: @@ -55,6 +34,20 @@ const data: ReferenceEntityTemplateSchema = { ], }, }, + subSections: [ + { + type: 'Generic', + anchorLink: 'best-practices', + title: 'Best practices', + sectionContent: ` +- **Choose appropriate direction:** Use \`block\` for vertical arrangements like forms. Use \`inline\` for horizontal arrangements like button groups. Note that inline wraps while block doesn't. +- **Use design system spacing:** Use \`SpacingKeyword\` values for consistency. Start with \`base\` and adjust as needed. +- **Apply alignment properties:** Use \`justifyContent\` for main axis distribution, \`alignItems\` for cross axis positioning, \`alignContent\` for extra space distribution. +- **Avoid percentages on mobile:** Don't use percentage-based sizing within scrollable containers on mobile surfaces. +- **Use gap for spacing control:** Use \`gap\` for uniform spacing, \`rowGap\` for block axis, \`columnGap\` for inline axis. +`, + }, + ], related: [], }; diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/Text/Text.doc.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/Text/Text.doc.ts index 411aa9064c..e92ed7830c 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/Text/Text.doc.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/Text/Text.doc.ts @@ -20,26 +20,6 @@ const data: ReferenceEntityTemplateSchema = { ], category: 'Polaris web components', subCategory: 'Layout and structure', - subSections: [ - { - type: 'Generic', - anchorLink: 'best-practices', - title: 'Best practices', - sectionContent: - '- **Choose semantic types:** Use `strong` for emphasis, `small` for secondary info, `generic` for standard text.\n' + - '- **Apply appropriate tones:** Use `success` for positive outcomes, `warning` or `critical` for alerts, `info` for helpful context, `auto` for neutral content.\n' + - '- **Balance color intensity:** Use `strong` for emphasis, `base` for readability, `subdued` for secondary info.\n' + - '- **Nest for mixed formatting:** Nest `Text` components when you need multiple styles within one text block.', - }, - { - type: 'Generic', - anchorLink: 'limitations', - title: 'Limitations', - sectionContent: - "- Text styling is controlled by the POS design system through the provided properties—custom font families, sizes, or styling beyond the available options aren't supported.\n" + - "- Complex rich text formatting isn't supported—use multiple `Text` components or nested text elements for varied formatting needs.", - }, - ], defaultExample: { image: 'text-default.png', description: @@ -54,6 +34,27 @@ const data: ReferenceEntityTemplateSchema = { ], }, }, + subSections: [ + { + type: 'Generic', + anchorLink: 'best-practices', + title: 'Best practices', + sectionContent: ` +- **Choose semantic types:** Use \`strong\` for emphasis, \`small\` for secondary info, \`generic\` for standard text. +- **Apply appropriate tones:** Use \`success\` for positive outcomes, \`warning\` or \`critical\` for alerts, \`info\` for helpful context, \`auto\` for neutral content. +- **Balance color intensity:** Use \`strong\` for emphasis, \`base\` for readability, \`subdued\` for secondary info. +- **Nest for mixed formatting:** Nest \`Text\` components when you need multiple styles within one text block. +`, + }, + { + type: 'Generic', + anchorLink: 'limitations', + title: 'Limitations', + sectionContent: ` +Complex rich text formatting isn't supported—use multiple \`Text\` components or nested text elements for varied formatting needs. +`, + }, + ], related: [], }; diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/TextArea/TextArea.doc.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/TextArea/TextArea.doc.ts index d7f8fbc1b4..87bb6c9fda 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/TextArea/TextArea.doc.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/TextArea/TextArea.doc.ts @@ -3,7 +3,7 @@ import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs'; const data: ReferenceEntityTemplateSchema = { name: 'TextArea', description: - 'The `TextArea` component captures longer text content with a multi-line, resizable text input area. Use it to collect descriptions, notes, comments, or other extended text input in forms and data entry workflows.' + + 'The `TextArea` component captures plain text content with a multi-line, resizable text input area. Use it to collect descriptions, notes, comments, or other extended text input in forms and data entry workflows.' + '\n\nThe component provides a multi-line text input area that accommodates longer content. It supports validation and multi-line formatting, making it ideal for capturing detailed information such as order notes, product descriptions, or customer feedback that requires more than single-line input.', thumbnail: 'text-area-thumbnail.png', isVisualComponent: true, @@ -30,26 +30,6 @@ const data: ReferenceEntityTemplateSchema = { ], category: 'Polaris web components', subCategory: 'Forms', - subSections: [ - { - type: 'Generic', - anchorLink: 'best-practices', - title: 'Best practices', - sectionContent: - '- **Set appropriate row count:** Use 2-3 rows for brief notes, 4-6 for descriptions, and more for extensive content.\n' + - '- **Show character limit feedback:** When approaching `maxLength`, display remaining characters in the `details` text.\n' + - '- **Write descriptive labels:** Use specific labels like "Product Description" or "Special Instructions" rather than generic terms.', - }, - { - type: 'Generic', - anchorLink: 'limitations', - title: 'Limitations', - sectionContent: - "- `TextArea` provides multi-line text input but doesn't include rich text formatting capabilities—complex formatting like bold, italic, or lists requires alternative solutions or plain text representations.\n" + - "- The `required` property adds semantic meaning only—it doesn't trigger automatic error display or validation, so you must implement validation logic manually.\n" + - "- The `accessory` slot supports only `Button` and `Clickable` components—other component types can't be used for field accessories.", - }, - ], defaultExample: { image: 'text-area-default.png', description: @@ -64,6 +44,26 @@ const data: ReferenceEntityTemplateSchema = { ], }, }, + subSections: [ + { + type: 'Generic', + anchorLink: 'best-practices', + title: 'Best practices', + sectionContent: ` +- **Set appropriate row count:** Use 2-3 \`rows\` for brief notes, 4-6 for descriptions, and more for extensive content. +- **Show character limit feedback:** When approaching \`maxLength\`, display remaining characters in the \`details\` text. +- **Write descriptive labels:** Use specific labels like "Product Description" or "Special Instructions" rather than generic terms. +`, + }, + { + type: 'Generic', + anchorLink: 'limitations', + title: 'Limitations', + sectionContent: ` +The \`accessory\` slot supports only [\`Button\`](/docs/api/pos-ui-extensions/2025-10/polaris-web-components/actions/button) and [\`Clickable\`](/docs/api/pos-ui-extensions/2025-10/polaris-web-components/actions/clickable) components. Other component types can't be used for field accessories. +`, + }, + ], related: [], examples: { description: @@ -71,7 +71,7 @@ const data: ReferenceEntityTemplateSchema = { examples: [ { description: - 'Add action buttons to the text area using the accessory slot for quick actions like clearing text or formatting content. This example shows how to use `s-button` and `s-clickable` components in the accessory slot, providing inline functionality within the multi-line input context.', + 'Add action buttons to the text area using the accessory slot for quick actions like clearing text or formatting content. This example shows how to use [`s-button`](/docs/api/pos-ui-extensions/2025-10/polaris-web-components/actions/button) and [`s-clickable`](/docs/api/pos-ui-extensions/2025-10/polaris-web-components/actions/clickable) components in the accessory slot, providing inline functionality within the multi-line input context.', codeblock: { title: 'Add accessory buttons', tabs: [ diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/TextField/TextField.doc.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/TextField/TextField.doc.ts index baff49d5ec..4515f0422d 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/TextField/TextField.doc.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/TextField/TextField.doc.ts @@ -3,7 +3,7 @@ import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs'; const data: ReferenceEntityTemplateSchema = { name: 'TextField', description: - 'The `TextField` component captures single-line text input. Use it to collect short, free-form information in forms and data entry workflows.' + + 'The `TextField` component captures single-line text input. Use it to collect short, free-form information in forms and data entry workflows. For multi-line text entry, use the [`TextArea`](/docs/api/pos-ui-extensions/2025-10/polaris-web-components/forms/textarea) component.' + '\n\nThe component supports various input configurations including placeholders, character limits, and validation. It includes built-in support for labels, helper text, and error states to guide merchants through data entry, ensuring accurate and efficient information capture across different retail scenarios.', thumbnail: 'text-field-thumbnail.png', isVisualComponent: true, @@ -30,26 +30,6 @@ const data: ReferenceEntityTemplateSchema = { ], category: 'Polaris web components', subCategory: 'Forms', - subSections: [ - { - type: 'Generic', - anchorLink: 'best-practices', - title: 'Best practices', - sectionContent: - '- **Use for single-line text input:** Choose `TextField` for short values like names, titles, or identifiers. For multi-line content, use `TextArea`.\n' + - '- **Show character limit feedback:** When approaching `maxLength`, display remaining characters in the `details` text.\n' + - '- **Write descriptive labels:** Use specific labels like "Product Name" or "Reference Code" rather than generic terms.', - }, - { - type: 'Generic', - anchorLink: 'limitations', - title: 'Limitations', - sectionContent: - '- `TextField` provides single-line text input only—multi-line text entry requires the `TextArea` component.\n' + - "- The `required` property adds semantic meaning only—it doesn't trigger automatic error display or validation, so you must implement validation logic manually.\n" + - "- The `accessory` slot supports only `Button` and `Clickable` components with text content only—other component types or complex layouts can't be used for field accessories.", - }, - ], defaultExample: { image: 'text-field-default.png', description: @@ -64,14 +44,34 @@ const data: ReferenceEntityTemplateSchema = { ], }, }, + subSections: [ + { + type: 'Generic', + anchorLink: 'best-practices', + title: 'Best practices', + sectionContent: ` +- **Use for single-line text input:** Choose \`TextField\` for short values like names, titles, or identifiers. For multi-line content, use [\`TextArea\`](/docs/api/pos-ui-extensions/2025-10/polaris-web-components/forms/textarea). +- **Show character limit feedback:** When approaching \`maxLength\`, display remaining characters in the \`details\` text. +- **Write descriptive labels:** Use specific labels like "Product Name" or "Reference Code" rather than generic terms. +`, + }, + { + type: 'Generic', + anchorLink: 'limitations', + title: 'Limitations', + sectionContent: ` +The \`accessory\` slot supports only [\`Button\`](/docs/api/pos-ui-extensions/2025-10/polaris-web-components/actions/button) and [\`Clickable\`](/docs/api/pos-ui-extensions/2025-10/polaris-web-components/actions/clickable) components with text content only—other component types or complex layouts can't be used for field accessories. +`, + }, + ], related: [], examples: { description: - 'Learn how to handle events, use accessory slots, and configure common properties for validation and user guidance.', + 'Learn how to add accessory buttons, configure validation properties, and handle events.', examples: [ { description: - 'Add action buttons to the text field using the accessory slot for quick actions like clearing text or submitting input. This example shows how to use `s-button` and `s-clickable` components with text content in the accessory slot, enabling inline actions without leaving the input context.', + 'Add action buttons to the text field using the accessory slot for quick actions like clearing text or submitting input. This example shows how to use [`s-button`](/docs/api/pos-ui-extensions/2025-10/polaris-web-components/actions/button) and [`s-clickable`](/docs/api/pos-ui-extensions/2025-10/polaris-web-components/actions/clickable) components with text content in the accessory slot, enabling inline actions without leaving the input context.', codeblock: { title: 'Add accessory buttons', tabs: [ diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/Tile/Tile.doc.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/Tile/Tile.doc.ts index 31831cb77b..e80e3a35b1 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/Tile/Tile.doc.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/Tile/Tile.doc.ts @@ -4,7 +4,9 @@ const data: ReferenceEntityTemplateSchema = { name: 'Tile', description: 'The `Tile` component displays interactive buttons for the POS smart grid that allow merchants to complete actions quickly. Tiles serve as customizable shortcuts that provide contextual information and enable merchants to quickly access workflows, actions, and information from the smart grid.' + - '\n\nTiles are dynamic components that can change their appearance, content, and enabled state based on surrounding context such as cart contents, device conditions, or runtime state. They support tap interactions, visual feedback, and can display contextual information through titles, subtitles, and badge values.', + '\n\nTiles are dynamic components that can change their appearance, content, and enabled state based on surrounding context such as cart contents, device conditions, or runtime state. They support tap interactions, visual feedback, and can display contextual information through titles, subtitles, and badge values.' + + "\n\nTo maintain a consistent visual experience, tile size and layout are determined by the smart grid system, and custom icons and images aren't supported." + + '\n\nEach POS UI extension can only render one `Tile` component for each [home screen tile target](/docs/api/pos-ui-extensions/2025-10/targets/home-screen#home-screen-tile-).', thumbnail: 'tile-thumbnail.png', isVisualComponent: true, type: '', @@ -24,30 +26,6 @@ const data: ReferenceEntityTemplateSchema = { ], category: 'Polaris web components', subCategory: 'Actions', - subSections: [ - { - type: 'Generic', - anchorLink: 'best-practices', - title: 'Best practices', - sectionContent: - '- **Write action-oriented headings:** Use specific language like "Apply loyalty discount" rather than generic terms like "Loyalty app."\n' + - '- **Provide contextual subheadings:** Show dynamic information like cart totals, eligibility requirements, or current status.\n' + - '- **Use meaningful item counts:** Display counts for actionable items like pending notifications or items requiring action, not just informational counts.\n' + - '- **Launch modals for workflows:** Use `onClick` with `shopify.action.presentModal()` rather than performing complex operations directly.', - }, - { - type: 'Generic', - anchorLink: 'limitations', - title: 'Limitations', - sectionContent: - '- Each POS UI extension can only render one `Tile` component per tile target.\n' + - "- The `itemCount` property only accepts numeric values—string or text badges aren't supported.\n" + - "- Custom icons, images, or visual styling beyond the built-in `tone` property aren't supported.\n" + - "- Tile size and layout are determined by the smart grid system and can't be customized.\n" + - "- The `Tile` component supports click and long press interactions only. Swipe, drag, and other gestures aren't supported.\n" + - "- The `heading` and `subheading` properties must be plain strings—HTML, markdown, or rich text formatting isn't supported.", - }, - ], defaultExample: { image: 'tile-default.png', description: @@ -62,6 +40,27 @@ const data: ReferenceEntityTemplateSchema = { ], }, }, + subSections: [ + { + type: 'Generic', + anchorLink: 'best-practices', + title: 'Best practices', + sectionContent: ` +- **Write action-oriented headings:** Use specific language like "Apply loyalty discount" rather than generic terms like "Loyalty app." +- **Provide contextual subheadings:** Show dynamic information like cart totals, eligibility requirements, or current status. +- **Use meaningful item counts:** Display counts for actionable items like pending notifications or items requiring action, not just informational counts. +- **Launch modals for workflows:** Use \`onClick\` with \`shopify.action.presentModal()\` rather than performing complex operations directly. +`, + }, + { + type: 'Generic', + anchorLink: 'limitations', + title: 'Limitations', + sectionContent: ` +The \`Tile\` component supports click and long press interactions only. Swipe, drag, and other gestures aren't supported. +`, + }, + ], related: [], }; diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/TimeField/TimeField.doc.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/TimeField/TimeField.doc.ts index 25a5cc82f6..10458e5e12 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/TimeField/TimeField.doc.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/TimeField/TimeField.doc.ts @@ -4,8 +4,9 @@ const data: ReferenceEntityTemplateSchema = { name: 'TimeField', description: 'The `TimeField` component captures time input with a consistent interface for time selection and validation. Use it to collect time information in scheduling, booking, or data entry workflows.' + - '\n\nThe component supports both 12-hour and 24-hour time formats based on locale settings, with built-in validation to ensure valid time entries. It includes features like time picker integration, keyboard shortcuts, and formatted display to streamline time entry for scheduling, appointment booking, and time-sensitive operations in retail environments.' + - '\n\n`TimeField` components respects merchant locale settings for default time format preferences while allowing manual override for specific use cases that require alternative formats.', + '\n\nThe component supports both 12-hour and 24-hour time formats based on locale settings. It includes features like time picker integration, keyboard shortcuts, and formatted display to streamline time entry for scheduling, appointment booking, and time-sensitive operations in retail environments.' + + '\n\n`TimeField` components respects merchant locale settings for default time format preferences while allowing manual override for specific use cases that require alternative formats.' + + '\n\n`TimeField` provides only text-based time input. For visual time selection with clock or spinner interfaces, use the [`TimePicker`](/docs/api/pos-ui-extensions/2025-10/polaris-web-components/forms/timepicker) component which offers interactive time selection.', thumbnail: 'time-field-thumbnail.png', isVisualComponent: true, type: '', @@ -25,25 +26,6 @@ const data: ReferenceEntityTemplateSchema = { ], category: 'Polaris web components', subCategory: 'Forms', - subSections: [ - { - type: 'Generic', - anchorLink: 'best-practices', - title: 'Best practices', - sectionContent: - '- **Use correct format:** Always use `HH:mm:ss` format with leading zeros (like `"09:05:00"` not `"9:5:0"`).\n' + - '- **Explain time constraints:** Use `details` to clarify requirements like "Business hours only (09:00-17:00)" or "Must be a future time."', - }, - { - type: 'Generic', - anchorLink: 'limitations', - title: 'Limitations', - sectionContent: - '- `TimeField` accepts time values in 24-hour `HH:mm:ss` format only—12-hour times or other formats require conversion before setting the value property.\n' + - '- The component provides text-based time input—for visual time selection with clock or spinner interfaces, use the `TimePicker` component which offers interactive time selection.\n' + - '- Validation occurs when the user finishes editing rather than on every keystroke—invalid times are only flagged after blur, which may delay error feedback.', - }, - ], defaultExample: { image: 'time-field-default.png', description: @@ -58,6 +40,17 @@ const data: ReferenceEntityTemplateSchema = { ], }, }, + subSections: [ + { + type: 'Generic', + anchorLink: 'best-practices', + title: 'Best practices', + sectionContent: ` +- **Use correct format:** Always use \`HH:mm:ss\` format with leading zeros (like \`"09:05:00"\` not \`"9:5:0"\`). +- **Explain time constraints:** Use \`details\` to clarify requirements like "Business hours only (09:00-17:00)" or "Must be a future time." +`, + }, + ], related: [], examples: { description: diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/TimePicker/TimePicker.doc.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/TimePicker/TimePicker.doc.ts index 01597712ee..bd2c73d25a 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/TimePicker/TimePicker.doc.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/TimePicker/TimePicker.doc.ts @@ -3,8 +3,8 @@ import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs'; const data: ReferenceEntityTemplateSchema = { name: 'TimePicker', description: - 'The `TimePicker` component allows merchants to select a specific time using an interactive picker interface. Use it to provide visual time selection for improved user experience and reduced input errors.' + - '\n\n`TimePicker` offers a more visual and touch-friendly alternative to text-based time input, making time selection faster and more accurate. The picker interface provides an intuitive way to select hours and minutes through an interactive interface.', + 'The `TimePicker` component allows merchants to select a specific time using an interactive picker interface. This offers a more visual and touch-friendly alternative to [text-based time input](/docs/api/pos-ui-extensions/2025-10/polaris-web-components/forms/timefield), making time selection faster and more accurate.' + + '\n\n`TimePicker` provides the picker interface but requires external state management for the selected value. You must manage the selected time value in your application state and update it using the `onChange` callback.', thumbnail: 'time-spinner-thumbnail.png', isVisualComponent: true, type: '', @@ -24,26 +24,6 @@ const data: ReferenceEntityTemplateSchema = { ], category: 'Polaris web components', subCategory: 'Forms', - subSections: [ - { - type: 'Generic', - anchorLink: 'best-practices', - title: 'Best practices', - sectionContent: - '- **Choose for visual time selection:** Use `TimePicker` when users benefit from a visual picker interface. Use `TimeField` when users know the exact time.\n' + - '- **Use correct format:** Always use `HH:mm:ss` format with leading zeros. The internal format is always 24-hour regardless of UI presentation.\n' + - '- **Validate before setting values:** Invalid values reset to empty string. Implement validation to show appropriate error messages.', - }, - { - type: 'Generic', - anchorLink: 'limitations', - title: 'Limitations', - sectionContent: - '- `TimePicker` provides the picker interface but requires external state management for the selected value—you must update the value property in response to change events.\n' + - '- The component uses 24-hour `HH:mm:ss` format internally—display formatting for 12-hour time or locale-specific formats requires additional formatting logic in your application.\n' + - '- Invalid time values result in an empty string without specific error feedback—you must validate time formats before setting the value property to provide meaningful error messages to users.', - }, - ], defaultExample: { image: 'time-spinner-default.png', description: @@ -58,6 +38,18 @@ const data: ReferenceEntityTemplateSchema = { ], }, }, + subSections: [ + { + type: 'Generic', + anchorLink: 'best-practices', + title: 'Best practices', + sectionContent: ` +- **Choose for visual time selection:** Use \`TimePicker\` when users benefit from a visual picker interface. Use [\`TimeField\`](/docs/api/pos-ui-extensions/2025-10/polaris-web-components/forms/timefield) when users know the exact time. +- **Use correct format:** Always use \`HH:mm:ss\` format with leading zeros. The internal format is always 24-hour regardless of UI presentation. +- **Validate before setting values:** Invalid values reset to empty string. Implement validation to show appropriate error messages. +`, + }, + ], related: [], examples: { description: