Update docs for editable property (#3002)

Resolves shop/issues-retail#8521

### Background

The changes made in #2986 need their documentation to be updated.

### Solution

Adds release notes for:
- Added `editable` property
- Added `useCartEditable` hook
- Added `CartNotEditableError` error class

This PR also changes the API method docs to use `Throws` instead of `@throws` as our internal documentation engine doesn't support those tags yet. Ideally, we'd be able to make use of such tags, but for now I think it makes sense to just do without them.

#### Question

Now `editable` affects all cart methods, throwing an error when the cart is not editable. Should we update all examples to include the `editable` check or is that simply noise?

For example, the react examples would probably look like:

```tsx
  const editable = useCartEditable();
  // ...
  return (
    <Tile 
      // ...
      onPress={() => editable && api.cart.setCustomer({
        id: 1,
      })}
    />
  );
```

And TypeScript examples would look like:

```ts
  const tile = root.createComponent(Tile, {
    // ...
    onPress: () => api.cart.subscribable.initial.editable && api.cart.setCustomer({
      id: 1,
    }),
  });
  // ...
 api.cart.subscribable.subscribe((newCart: Cart) => {
    tile.updateProps({
      onPress: () => editable && api.cart.setCustomer({
        id: 1,
      }),
    });
  });
```

Note that the other way of handling cart editability is to disable the tile when `editable` is false. So we could also update the examples in a similar way but just modifying `enabled` instead of doing `editable && ...`.

How do we feel about including these in the examples? Does it detract from the actual example too much?

### 🎩

https://pos.docs.shopify.io/extensions/contributing/documentation#how-to-update-docs-for-stable-api-versions

Here is the result:

| API Docs | Release Notes | Example |
| -------- | ------------- | ------- |
| ![Cart API Docs](https://graphite-user-uploaded-assets-prod.s3.amazonaws.com/By4mWXXRgKfL1doS4Lif/013312bb-9d0e-4918-954e-0ae3e015dfac.png) | ![Release Notes](https://graphite-user-uploaded-assets-prod.s3.amazonaws.com/By4mWXXRgKfL1doS4Lif/b12e9815-22fe-4f7e-91d1-1614c8e053ed.png) | ![Example](https://graphite-user-uploaded-assets-prod.s3.amazonaws.com/By4mWXXRgKfL1doS4Lif/032fb943-24ae-4107-9362-743b36d4a1db.png) |

### Checklist

- [x] I have 🎩'd these changes
- [x] I have updated relevant documentation

Author: MrGVSV

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

@@ -44,6 +44,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>;
 }

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

@@ -4,6 +4,8 @@ type CartApiMethods = Omit<CartApiContent, 'subscribable'>;
 
 /**
  * An error thrown when an attempt to edit the cart is made while it is not editable.
+ *
+ * @deprecated the cart will now throw a generic `Error`
  */
 export class CartNotEditableError extends Error {
   constructor(