Merge pull request #3082 from Shopify/vic/backfill-editable

Backfill editable changes to 2025-10

Author: vctrchu

packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/cart-api.doc.ts

@@ -45,6 +45,12 @@ The Cart API enables UI Extensions to manage and interact with POS cart contents
           'subscribable',
         ),
       },
+      {
+        codeblock: generateCodeBlockForCartApi(
+          'Check editable state of the cart',
+          'check-cart-editable',
+        ),
+      },
       {
         codeblock: generateCodeBlockForCartApi(
           'Apply a cart level discount',

packages/ui-extensions/docs/surfaces/point-of-sale/reference/examples/cart-api/check-cart-editable.ts

@@ -0,0 +1,16 @@
+import {Cart, Tile, extension} from '@shopify/ui-extensions/point-of-sale';
+
+export default extension('pos.home.tile.render', (root, api) => {
+  const tile = root.createComponent(Tile, {
+    title: 'My App',
+    enabled: api.cart.subscribable.initial.editable ?? true,
+  });
+
+  api.cart.subscribable.subscribe((newCart: Cart) => {
+    tile.updateProps({
+      enabled: newCart.editable ?? true
+    });
+  });
+
+  root.append(tile);
+});

packages/ui-extensions/docs/surfaces/point-of-sale/reference/examples/cart-api/check-cart-editable.tsx

@@ -0,0 +1,15 @@
+import React from 'react';
+import {
+  reactExtension,
+  Tile,
+  useApi,
+  useCartEditable,
+} from '@shopify/ui-extensions-react/point-of-sale';
+
+const SmartGridTile = () => {
+  const editable = useCartEditable();
+
+  return <Tile title="My App" enabled={editable} />;
+};
+
+export default reactExtension('pos.home.tile.render', () => <SmartGridTile />);

packages/ui-extensions/docs/surfaces/point-of-sale/staticPages/pages/versions.doc.ts

@@ -15,27 +15,80 @@ const data: LandingTemplateSchema = {
   sections: [
     {
       type: 'Generic',
-      anchorLink: 'support-policy',
-      title: 'Support Policy',
-      sectionContent: '',
-      sectionNotice: [
-        {
-          title: 'End of Support Plan',
-          type: 'Warning',
-          sectionContent: `
-          To ensure the best possible ongoing POS UI Extension development experience, starting in April 2025, we will end support for versions on a one-year rolling basis. This table details the end of support schedule.
-
-|released version|removed versions|
-|---:|---|
-|2025-04|1.0.0, 1.0.1, 1.1.2, 1.2.0, 1.3.0, 1.4.0, 1.5.1, 1.6.0, 1.7.0, 2024-04|
-|2025-07|2024-07|
-|2025-10|2024-10|
-|2026-01|2025-01|
-|2026-04|2025-04|
-
-Refer to the [migration guide](/docs/api/pos-ui-extensions/migrating) for more information.`,
-        },
-      ],
+      anchorLink: '202507',
+      title: '2025.07',
+      sectionContent: `
+- Added in POS version: 10.6
+- Release day: 07/03/2025
+
+## Breaking Changes
+
+- Removed the deprecated \`FormattedTextField\` component. Use the [TextField](/docs/api/pos-ui-extensions/components/textfield) component instead. It will continue to work in POS 10.6.0, but will no longer function in POS 10.7.0.
+
+## Deprecations
+
+- Deprecated \`'minor'\`, \`'major'\`, \`'spot'\`, \`'caption'\`, \`'badge'\` as values for the \`size\` prop in the [Icon](/docs/api/pos-ui-extensions/components/icon) component. Use \`'s'\`, \`'m'\`, \`'l'\`, \`'xl'\` instead.
+- Deprecated \`'arrow'\`, \`'available-at-other-locations'\`, \`'collections'\`, \`'connectivity-warning'\`, \`'delivery'\`, \`'home'\`, \`'image-placeholder'\`, \`'internet'\`, \`'menu'\`, \`'orders'\`, \`'products'\`, \`'shipment'\` as values for the \`name\` prop in the [Icon](/docs/api/pos-ui-extensions/components/icon) component. See valid values for [\`IconName\`](/docs/api/pos-ui-extensions/latest/components/icon#icon-propertydetail-name).
+
+## Important Fixes
+
+- Updated [pos.draft-order-details.block.render](https://shopify.dev/docs/api/pos-ui-extensions/targets/draft-order-details/pos-draft-order-details-block-render) to allow the proper set of components, called \`BlockComponents\`. Previously, this target erroneously accepted \`ActionComponents\`, which are intended for targets like \`pos.draft-order-details.action.render\`.
+
+### Features
+
+- Added support for [Direct API access](/docs/api/pos-ui-extensions#direct-api-access), and [authenticated requests](/docs/api/pos-ui-extensions#app-authentication).
+- Added required \`posVersion\` property to [Session](/docs/api/pos-ui-extensions/apis/session-api) interface.
+- Added optional \`currency\` property to [Discount](/docs/api/pos-ui-extensions/apis/cart-line-item-api#cartlineitemapi-propertydetail-cartlineitem) interface.
+- Added \`executedAt\` property to [BaseTransactionComplete](/docs/api/pos-ui-extensions/targets/receipts/pos-receipt-footer-block-render#transactioncompletewithreprintdata-propertydetail-transaction) interface.
+- Added optional \`exchangeId\` and \`returnId\` property to [ReturnTransactionData](/docs/api/pos-ui-extensions/targets/receipts/pos-receipt-footer-block-render#transactioncompletewithreprintdata-propertydetail-transaction) interface.
+- Added required \`variantId\` property to [ProductApi](/docs/api/pos-ui-extensions/apis/product-api#productapi-propertydetail-variantid) interface.
+- Added optional \`taxLines\` property to [ShippingLine](/docs/api/pos-ui-extensions/targets/post-transaction/pos-transaction-complete-event-observe#transactioncompletedata-propertydetail-transaction) interface.
+- Added optional \`onBlur\` handler to [SearchBar](/docs/api/pos-ui-extensions/components/searchbar) component.
+- Added optional \`tone\` property to [Icon](/docs/api/pos-ui-extensions/components/icon) component and expanded \`name\` and \`size\` options.
+- Added optional \`editable\` property to \`Cart\` interface.
+- Added \`useCartEditable\` hook to access the cart's editable state.
+
+### Developer Preview
+
+  - Introduced a [Storage API](/docs/api/pos-ui-extensions/apis/storage-api). The Storage API gives the UI Extension access to store data on the POS device that the extension is running on.
+  - Added support for the ${TargetLink.PosExchangePostActionMenuItemRender}, ${TargetLink.PosExchangePostActionRender}, ${TargetLink.PosExchangePostBlockRender} targets.
+  - Added support for the ${TargetLink.PosReturnPostActionMenuItemRender}, ${TargetLink.PosReturnPostActionRender}, ${TargetLink.PosReturnPostBlockRender} targets.
+  `,
+    },
+    {
+      type: 'Generic',
+      anchorLink: '202504',
+      title: '2025.04',
+      sectionContent: `
+- Added in POS version: 9.31
+- Release day: 04/01/2025
+
+## Important Fixes
+
+- **POS 10.3.0**:
+
+  - Fixed an issue where the \`TextField\` component failed to apply the \`maxLength\` parameter.
+
+- **POS 10.2.0**:
+
+  - Fixed a sizing issue with the \`Button\` component.
+  - Fixed an issue where the \`Section\` component was displaying a divider between child components.
+
+- **POS 10.0.0**:
+
+  - Removed \`email\`, \`firstName\`, \`lastName\`, and \`note\` from the [Customer](/docs/api/pos-ui-extensions/apis/cart-api#customer) object.
+  - POS UI Extensions components automatically use our new POS visual design language.
+
+### Features
+
+**Developer Preview**:
+  - Added support for the ${TargetLink.PosTransactionCompleteObserve} target.
+  - Added support for cash tracking session. ${TargetLink.PosCashTrackingSessionStartObserve}, ${TargetLink.PosCashTrackingSessionCompleteObserve} targets.
+  - Added support for the ${TargetLink.PosCartUpdateObserve} target.
+  - Added support for the ${TargetLink.PosReceiptFooterBlockRender} target.
+  - Introduced a [POSReceiptBlock component](/docs/api/pos-ui-extensions/components/posreceiptblock). It's the required parent component for ${TargetLink.PosReceiptFooterBlockRender} targets.
+  - Introduced a [QRCode component](/docs/api/pos-ui-extensions/components/qrcode). It can be used to render a QR code in POS receipts but must be within a [POSReceiptBlock component](/docs/api/pos-ui-extensions/components/posreceiptblock).
+  `,
     },
     {
       type: 'Generic',

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

@@ -30,19 +30,17 @@ export interface CartApiContent {
   subscribable: RemoteSubscribable<Cart>;
 
   /** Bulk update the cart
+   *
    * @param cartState the cart state to set
    * @returns the updated cart
-   *
-   * @throws CartNotEditableError if the cart is not currently editable.
    */
   bulkCartUpdate(cartState: CartUpdateInput): Promise<Cart>;
 
   /** Apply a cart level discount
+   *
    * @param type the type of discount applied (example: 'Percentage')
    * @param title the title attributed with the discount
    * @param amount the percentage or fixed monetary amount deducted with the discount. Pass in `undefined` if using discount codes.
-   *
-   * @throws CartNotEditableError if the cart is not currently editable.
    */
   applyCartDiscount(
     type: CartDiscountType,
@@ -52,98 +50,83 @@ export interface CartApiContent {
 
   /**
    * Add a code discount to the cart
-   * @param code the code for the discount to add to the cart
    *
-   * @throws CartNotEditableError if the cart is not currently editable.
+   * @param code the code for the discount to add to the cart
    */
   addCartCodeDiscount(code: string): Promise<void>;
 
   /**
    * Remove the cart discount
-   *
-   * @throws CartNotEditableError if the cart is not currently editable.
    */
   removeCartDiscount(): Promise<void>;
 
   /**
    * Remove all cart and line item discounts
-   * @param disableAutomaticDiscounts Whether or not automatic discounts should be enabled after removing the discounts.
    *
-   * @throws CartNotEditableError if the cart is not currently editable.
+   * @param disableAutomaticDiscounts Whether or not automatic discounts should be enabled after removing the discounts.
    */
   removeAllDiscounts(disableAutomaticDiscounts: boolean): Promise<void>;
 
   /**
    * Clear the cart
-   *
-   * @throws CartNotEditableError if the cart is not currently editable.
    */
   clearCart(): Promise<void>;
 
   /**
    * Set the customer in the cart
-   * @param customer the customer object to add to the cart
    *
-   * @throws CartNotEditableError if the cart is not currently editable.
+   * @param customer the customer object to add to the cart
    */
   setCustomer(customer: Customer): Promise<void>;
 
   /**
    * Remove the current customer from the cart
-   *
-   * @throws CartNotEditableError if the cart is not currently editable.
    */
   removeCustomer(): Promise<void>;
 
   /**
    * Add a custom sale to the cart
+   *
    * @param customSale the custom sale object to add to the cart
    * @returns {string} the uuid of the line item added
-   *
-   * @throws CartNotEditableError if the cart is not currently editable.
    */
   addCustomSale(customSale: CustomSale): Promise<string>;
 
   /**
    * Add a line item by variant ID to the cart
+   *
    * @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
-   *
-   * @throws CartNotEditableError if the cart is not currently editable.
    */
   addLineItem(variantId: number, quantity: number): Promise<string>;
 
   /**
    * Remove the line item at this uuid from the cart
-   * @param uuid the uuid of the line item that should be removed
    *
-   * @throws CartNotEditableError if the cart is not currently editable.
+   * @param uuid the uuid of the line item that should be removed
    */
   removeLineItem(uuid: string): Promise<void>;
 
   /**
    * Adds custom properties to the cart
-   * @param properties the custom key to value object to attribute to the cart
    *
-   * @throws CartNotEditableError if the cart is not currently editable.
+   * @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
-   * @param keys the collection of keys to be removed from the cart properties
    *
-   * @throws CartNotEditableError if the cart is not currently editable.
+   * @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
+   *
    * @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
-   *
-   * @throws CartNotEditableError if the cart is not currently editable.
    */
   addLineItemProperties(
     uuid: string,
@@ -152,31 +135,28 @@ export interface CartApiContent {
 
   /**
    * Adds custom properties to multiple line items at the same time.
-   * @param lineItemProperties the collection of custom line item properties to apply to their respective line items.
    *
-   * @throws CartNotEditableError if the cart is not currently editable.
+   * @param lineItemProperties the collection of custom line item properties to apply to their respective line items.
    */
   bulkAddLineItemProperties(
     lineItemProperties: SetLineItemPropertiesInput[],
   ): Promise<void>;
 
   /**
    * Removes the specified line item properties
+   *
    * @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
-   *
-   * @throws CartNotEditableError if the cart is not currently editable.
    */
   removeLineItemProperties(uuid: string, keys: string[]): Promise<void>;
 
   /**
    * Add a discount on a line item to the cart
+   *
    * @param uuid the uuid of the line item that should receive a discount
    * @param type the type of discount applied (example: 'Percentage')
    * @param title the title attributed with the discount
    * @param amount the percentage or fixed monetary amount deducted with the discout
-   *
-   * @throws CartNotEditableError if the cart is not currently editable.
    */
   setLineItemDiscount(
     uuid: string,
@@ -187,28 +167,25 @@ export interface CartApiContent {
 
   /**
    * Set line item discounts to multiple line items at the same time.
-   * @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.
    *
-   * @throws CartNotEditableError if the cart is not currently editable.
+   * @param lineItemDiscounts a map of discounts to add. They key is the uuid of the line item you want to add the discount to. The value is the discount input.
    */
   bulkSetLineItemDiscounts(
     lineItemDiscounts: SetLineItemDiscountInput[],
   ): Promise<void>;
 
   /**
    * Sets an attributed staff to all line items in the cart.
-   * @param staffId the ID of the staff. Providing undefined will clear the attributed staff from all line items.
    *
-   * @throws CartNotEditableError if the cart is not currently editable.
+   * @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.
+   *
    * @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.
-   *
-   * @throws CartNotEditableError if the cart is not currently editable.
    */
   setAttributedStaffToLineItem(
     staffId: number | undefined,
@@ -217,33 +194,29 @@ export interface CartApiContent {
 
   /**
    * Remove all discounts from a line item
-   * @param uuid the uuid of the line item whose discounts should be removed
    *
-   * @throws CartNotEditableError if the cart is not currently editable.
+   * @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)
-   * @param address the address object to add to the customer in cart
    *
-   * @throws CartNotEditableError if the cart is not currently editable.
+   * @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)
-   * @param addressId the address ID to delete
    *
-   * @throws CartNotEditableError if the cart is not currently editable.
+   * @param addressId the address ID to delete
    */
   deleteAddress(addressId: number): Promise<void>;
 
   /**
    * Update the default address for the customer (Customer must be present)
-   * @param addressId the address ID to set as the default address
    *
-   * @throws CartNotEditableError if the cart is not currently editable.
+   * @param addressId the address ID to set as the default address
    */
   updateDefaultAddress(addressId: number): Promise<void>;
 }