Improved API and prop descriptions fo 2025-10

Component prop descriptions

Component descriptions in index page cards

Event data descriptions

Type descriptions

component descriptions

lint

Prop description fixes

Additional context in descriptions

contractions

break up longer descs

remove enhanced / improved language

Author: mcvinci

packages/ui-extensions/src/shared.ts

@@ -940,15 +940,25 @@ export interface GraphQLError {
 }
 
 /**
- * Represents a read-only value managed on the main thread that an extension can subscribe to.
- *
- * Example: Checkout uses this to manage the state of an object and
- * communicate state changes to extensions running in a sandboxed web worker.
- *
- * This interface is compatible with [Preact's ReadonlySignal](https://github.com/preactjs/signals/blob/a023a132a81bd4ba4a0bebb8cbbeffbd8c8bbafc/packages/core/src/index.ts#L700-L709).
+ * Represents a reactive signal interface that provides both immediate value access and subscription-based updates. Enables real-time synchronization with changing data through the observer pattern.
  *
+ * This interface is compatible with [Preact's `ReadonlySignal`](https://github.com/preactjs/signals/blob/a023a132a81bd4ba4a0bebb8cbbeffbd8c8bbafc/packages/core/src/index.ts#L700-L709), allowing integration with Preact's reactive primitives.
  */
 export interface ReadonlySignalLike<T> {
+  /**
+   * The current value of the signal at this moment in time. This property provides immediate, synchronous access to the current state without requiring subscription setup or callbacks.
+   *
+   * The value is read-only—it cannot be modified directly and changes only through the underlying data source (for example, when locale changes, connectivity state toggles, or cart updates occur). Reading this property does not trigger any side effects or subscriptions—it simply returns the current value.
+   *
+   * Commonly accessed for one-time value checks, initial setup, synchronous conditional logic, or when subscriptions aren't needed (for example, reading current locale once during initialization, checking connectivity status before an operation, or displaying current cart total in a snapshot).
+   */
   readonly value: T;
+  /**
+   * Subscribes to value changes and executes the provided callback function whenever the underlying value updates. The callback receives the new value as its parameter and is invoked immediately with the current value upon subscription, then again each time the value changes thereafter.
+   *
+   * Returns a cleanup function that, when called, unsubscribes from further updates and prevents memory leaks. The cleanup function should be called when the component unmounts, the subscription is no longer needed, or when setting up a new subscription to replace the old one.
+   *
+   * Subscriptions are passive—they don't trigger changes, only react to them. Multiple subscriptions can exist simultaneously, each receiving updates independently. Commonly used to automatically update UI when data changes (reactive rendering), implement event-driven logic, keep multiple parts of the extension synchronized, or respond to external state changes without polling.
+   */
   subscribe(fn: (value: T) => void): () => void;
 }

packages/ui-extensions/src/surfaces/point-of-sale/api/action-api/action-api.ts

@@ -1,14 +1,16 @@
 export interface ActionApiContent {
-  /** Presents the `action-overlay.render` extension target on top of present view.
+  /**
+   * Presents the corresponding action (modal) target extension target as a full-screen modal overlay on top of the current view. The modal target is automatically determined based on the current extension point—for example, calling this from `pos.purchase.post.action.menu-item.render` presents the `pos.purchase.post.action.render` modal target.
    *
-   * For example: if we are calling presentModal() from pos.purchase.post.action.menu-item.render,
-   * it should present pos.purchase.post.action.render.
+   * The modal appears with a standard header (typically including a close button and title), occupies the full screen with proper backdrop/overlay, and blocks interaction with the underlying content until dismissed. The modal can be closed programmatically using `window.close()` or by the user dismissing it through UI controls. The method returns immediately without waiting for modal dismissal.
+   *
+   * Commonly used to launch detailed workflows requiring full screen space (multi-step wizards, complex forms, detailed product configuration), display rich content (product galleries, reports, charts), or present flows that need user focus without distractions from the main POS interface.
    */
   presentModal(): void;
 }
 
 /**
- * Access the Action API to present your app in a full screen modal.
+ * The `ActionApi` object provides methods for presenting modal interfaces. Access these methods through `shopify.action` to launch full-screen modal experiences.
  */
 export interface ActionApi {
   action: ActionApiContent;

packages/ui-extensions/src/surfaces/point-of-sale/api/cart-api/cart-api.ts

@@ -11,31 +11,38 @@ import type {
 } from '../../types/cart';
 
 /**
- * Access and modify the merchant’s current cart.
+ * The `CartApi` object provides access to cart management functionality and real-time cart state monitoring. Access these properties through `shopify.cart` to interact with the current POS cart.
  */
 export interface CartApi {
   cart: CartApiContent;
 }
 
+/**
+ * Defines the type of discount applied at the cart level. Specifies whether the discount is percentage-based, fixed amount, or discount code redemption.
+ */
 export type CartDiscountType = 'Percentage' | 'FixedAmount' | 'Code';
 
+/**
+ * Defines the type of discount applied to individual line items. Specifies whether the discount is percentage-based or a fixed amount reduction.
+ */
 export type LineItemDiscountType = 'Percentage' | 'FixedAmount';
 
 export interface CartApiContent {
   /**
-   * Provides read-only access to the current cart state and allows subscribing to cart changes.
-   * The `value` property provides the current cart state, and `subscribe` allows listening to changes.
+   * Provides read-only access to the current cart state and allows subscribing to cart changes. The `value` property provides the current cart state, and `subscribe` allows listening to changes.
    */
   current: ReadonlySignalLike<Cart>;
 
-  /** Bulk update the cart
+  /**
+   * Perform a bulk update of the entire cart state including note, discounts, customer, line items, and properties. Returns the updated cart object after the operation completes.
    *
    * @param cartState the cart state to set
    * @returns the updated cart
    */
   bulkCartUpdate(cartState: CartUpdateInput): Promise<Cart>;
 
-  /** Apply a cart level discount
+  /**
+   * Apply a cart-level discount with the specified type (`'Percentage'`, `'FixedAmount'`, or `'Code'`), title, and optional amount. For discount codes, omit the `amount` parameter. Enhanced validation ensures proper discount application.
    *
    * @param type the type of discount applied (example: 'Percentage')
    * @param title the title attributed with the discount
@@ -48,84 +55,82 @@ export interface CartApiContent {
   ): Promise<void>;
 
   /**
-   * Add a code discount to the cart
+   * Apply a discount code to the cart. The system will validate the code and apply the appropriate discount if the code is valid and applicable to the current cart contents.
    *
    * @param code the code for the discount to add to the cart
    */
   addCartCodeDiscount(code: string): Promise<void>;
 
   /**
-   * Remove the cart discount
+   * Remove the current cart-level discount. This only affects cart-level discounts and doesn't impact line item discounts or automatic discount eligibility.
    */
   removeCartDiscount(): Promise<void>;
 
   /**
-   * Remove all cart and line item discounts
+   * Remove all discounts from both the cart and individual line items. Set `disableAutomaticDiscounts` to `true` to prevent automatic discounts from being reapplied after removal.
    *
    * @param disableAutomaticDiscounts Whether or not automatic discounts should be enabled after removing the discounts.
    */
   removeAllDiscounts(disableAutomaticDiscounts: boolean): Promise<void>;
 
   /**
-   * Clear the cart
+   * Remove all line items and reset the cart to an empty state. This action can't be undone and will clear all cart contents including line items, discounts, properties, and selling plans.
    */
   clearCart(): Promise<void>;
 
   /**
-   * Set the customer in the cart
+   * Associate a customer with the current cart using the customer object containing the customer `ID`. This enables customer-specific pricing, discounts, and checkout features with customer data validation.
    *
    * @param customer the customer object to add to the cart
    */
   setCustomer(customer: Customer): Promise<void>;
 
   /**
-   * Remove the current customer from the cart
+   * Remove the currently associated customer from the cart, converting it back to a guest cart without customer-specific benefits or information while preserving cart contents.
    */
   removeCustomer(): Promise<void>;
 
   /**
-   * Add a custom sale to the cart
+   * Add a custom sale item to the cart with specified quantity, title, price, and taxable status. Returns the [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier) of the created line item for future operations and property management.
    *
    * @param customSale the custom sale object to add to the cart
-   * @returns {string} the uuid of the line item added
+   * @returns {string} the UUID of the line item added
    */
   addCustomSale(customSale: CustomSale): Promise<string>;
 
   /**
-   * Add a line item by variant ID to the cart.
-   * Returns the uuid of the line item added, or the empty string if the user dismissed an oversell guard modal without adding anything.
-   * Throws if POS fails to add the line item. Throws if POS fails to add the line item.
+   * Add a product variant to the cart by its numeric `ID` with the specified quantity. Returns the [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier) of the newly added line item, or an empty string if the user dismissed an oversell guard modal. Throws an error if POS fails to add the line item due to validation or system errors.
    *
    * @param variantId the product variant's numeric ID to add to the cart
    * @param quantity the number of this variant to add to the cart
-   * @returns {string} the uuid of the line item added, or the empty string if the user dismissed an oversell guard modal
+   * @returns {string} the UUID of the line item added, or the empty string if the user dismissed an oversell guard modal
    * @throws {Error} if POS fails to add the line item
    */
   addLineItem(variantId: number, quantity: number): Promise<string>;
 
   /**
-   * Remove the line item at this uuid from the cart
+   * Remove a specific line item from the cart using its [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier). The line item will be completely removed from the cart along with any associated discounts, properties, or selling plans.
    *
    * @param uuid the uuid of the line item that should be removed
    */
   removeLineItem(uuid: string): Promise<void>;
 
   /**
-   * Adds custom properties to the cart
+   * Add custom key-value properties to the cart for storing metadata, tracking information, or integration data. Properties are merged with existing cart properties.
    *
    * @param properties the custom key to value object to attribute to the cart
    */
   addCartProperties(properties: Record<string, string>): Promise<void>;
 
   /**
-   * Removes the specified cart properties
+   * Remove specific cart properties by their keys. Only the specified property keys will be removed while other properties remain intact.
    *
    * @param keys the collection of keys to be removed from the cart properties
    */
   removeCartProperties(keys: string[]): Promise<void>;
 
   /**
-   * Adds custom properties to the specified line item
+   * Add custom properties to a specific line item using its [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier). Properties are merged with existing line item properties for metadata storage and tracking.
    *
    * @param uuid the uuid of the line item to which the properties should be stringd
    * @param properties the custom key to value object to attribute to the line item
@@ -136,7 +141,7 @@ export interface CartApiContent {
   ): Promise<void>;
 
   /**
-   * Adds custom properties to multiple line items at the same time.
+   * Add properties to multiple line items simultaneously using an array of inputs containing line item [UUIDs](https://en.wikipedia.org/wiki/Universally_unique_identifier) and their respective properties for efficient bulk operations.
    *
    * @param lineItemProperties the collection of custom line item properties to apply to their respective line items.
    */
@@ -145,15 +150,15 @@ export interface CartApiContent {
   ): Promise<void>;
 
   /**
-   * Removes the specified line item properties
+   * Remove specific properties from a line item by `UUID` and property keys. Only the specified keys will be removed while other properties remain intact.
    *
    * @param uuid the uuid of the line item to which the properties should be removed
    * @param keys the collection of keys to be removed from the line item properties
    */
   removeLineItemProperties(uuid: string, keys: string[]): Promise<void>;
 
   /**
-   * Add a discount on a line item to the cart
+   * Apply a discount to a specific line item using its [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier). Specify the discount type (`'Percentage'` or `'FixedAmount'`), title, and amount value.
    *
    * @param uuid the uuid of the line item that should receive a discount
    * @param type the type of discount applied (example: 'Percentage')
@@ -168,7 +173,7 @@ export interface CartApiContent {
   ): Promise<void>;
 
   /**
-   * Set line item discounts to multiple line items at the same time.
+   * Apply discounts to multiple line items simultaneously. Each input specifies the line item `UUID` and discount details for efficient bulk discount operations.
    *
    * @param lineItemDiscounts a map of discounts to add. They key is the uuid of the line item you want to add the discount to. The value is the discount input.
    */
@@ -177,14 +182,14 @@ export interface CartApiContent {
   ): Promise<void>;
 
   /**
-   * Sets an attributed staff to all line items in the cart.
+   * Set the attributed staff member for all line items in the cart using the staff `ID`. Pass `undefined` to clear staff attribution from all line items.
    *
    * @param staffId the ID of the staff. Providing undefined will clear the attributed staff from all line items.
    */
   setAttributedStaff(staffId: number | undefined): Promise<void>;
 
   /**
-   * Sets an attributed staff to a specific line items in the cart.
+   * Set the attributed staff member for a specific line item using the staff `ID` and line item `UUID`. Pass `undefined` as `staffId` to clear attribution from the line item.
    *
    * @param staffId the ID of the staff. Providing undefined will clear the attributed staff on the line item.
    * @param lineItemUuid the UUID of the line item.
@@ -195,43 +200,43 @@ export interface CartApiContent {
   ): Promise<void>;
 
   /**
-   * Remove all discounts from a line item
+   * Remove all discounts from a specific line item identified by its `UUID`. This will clear any custom discounts applied to the line item while preserving discount allocation history.
    *
    * @param uuid the uuid of the line item whose discounts should be removed
    */
   removeLineItemDiscount(uuid: string): Promise<void>;
 
   /**
-   * Add an address to the customer (Customer must be present)
+   * Add a new address to the customer associated with the cart. The customer must be present in the cart before adding addresses.
    *
    * @param address the address object to add to the customer in cart
    */
   addAddress(address: Address): Promise<void>;
 
   /**
-   * Delete an address from the customer (Customer must be present)
+   * Delete an existing address from the customer using the address `ID`. The customer must be present in the cart to perform this operation.
    *
    * @param addressId the address ID to delete
    */
   deleteAddress(addressId: number): Promise<void>;
 
   /**
-   * Update the default address for the customer (Customer must be present)
+   * Set a specific address as the default address for the customer using the address `ID`. The customer must be present in the cart to update the default address.
    *
    * @param addressId the address ID to set as the default address
    */
   updateDefaultAddress(addressId: number): Promise<void>;
 
   /**
-   * Add a selling plan to a line item in the cart.
+   * Add a selling plan to a line item in the cart using the line item `UUID` and selling plan `ID`. Optionally provide the selling plan name, otherwise POS will fetch it after syncing the cart.
    *
    * @param uuid the uuid of the line item that should receive the selling plan
    * @param sellingPlanId the ID of the selling plan to add to the line item
    */
   addLineItemSellingPlan(input: SetLineItemSellingPlanInput): Promise<void>;
 
   /**
-   * Remove the selling plan from a line item in the cart.
+   * Remove the selling plan from a line item in the cart using the line item `UUID`. This will clear any subscription or recurring purchase configuration from the line item.
    *
    * @param uuid the uuid of the line item whose selling plan should be removed
    */

packages/ui-extensions/src/surfaces/point-of-sale/api/cart-line-item-api/cart-line-item-api.ts

@@ -1,11 +1,15 @@
 import type {LineItem} from '../../types/cart';
 
 /**
- * Access to the selected line item in the merchant’s current cart.
+ * The `CartLineItemApi` object provides access to the current cart line item in line item-specific extension contexts. Access this property through `shopify.cartLineItem` to retrieve detailed information about the specific cart line item currently being viewed or interacted with.
  */
 export interface CartLineItemApi {
   /**
-   * The selected line item in the merchant’s current cart.
+   * The complete line item object representing the selected item in the merchant's current cart. Contains all line item data including product identification (`productId`, `variantId`), display information (`title`, `vendor`, `sku`), pricing details (`price`), quantity, tax information (`taxable`, `taxLines`), applied discounts (`discounts`, `discountAllocations`), custom properties (`properties`), selling plan configuration (`sellingPlan`), and unique identifier (`uuid`).
+   *
+   * This represents the line item's current state at the moment the extension is triggered, reflecting all modifications, discounts, and properties. The line item object is read-only in this context—modifications should be made through the Cart API methods using the line item's `uuid`.
+   *
+   * Commonly used for displaying detailed item information, implementing item-specific business logic (restrictions, validations, special handling), showing custom line item properties, calculating item-level totals with discounts, or building line item configuration interfaces.
    */
   cartLineItem: LineItem;
 }