Merge pull request #3080 from Shopify/vic/editable-cart-api-backfill

Backfill editable changes for CartApi

Author: vctrchu

.changeset/gold-balloons-tan.md

@@ -0,0 +1,5 @@
+---
+'@shopify/ui-extensions': patch
+---
+
+Remove CartNotEditableError for POS CartApi

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

@@ -45,6 +45,8 @@ const data: LandingTemplateSchema = {
 - 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
 

packages/ui-extensions/src/surfaces/point-of-sale/render/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>;
 }