Add deprecation warning to renderMode (#4509)

### Background

Closes shop/issues-checkout#11640  
vault [decision](https://vault.shopify.io/gsd/decisions/10586) 

Following the introduction of split ship and pickup the `purchase.checkout.pickup-location-option-item.render-after` target is now shared between rendering inline and in a modal. The decision was made to not support modal within modal functionality and to not encourage third party developers to build solutions which utilize this. To be consistent across checkout this thinking should hold true for other targets that render both inline and in a modal:  
`purchase.checkout.shipping-option-item.render-after`  
`purchase.checkout.shipping-option-item.details.render`

renderMode should be deprecated today and the blocking of modal within modal functionality will occur in the future once the renderMode has been removed

### Solution

Add a deprecation warning for renderMode on ShippingOptionItem

### Checklist

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

Author: james-a-c

.changeset/ripe-chairs-cry.md

@@ -0,0 +1,5 @@
+---
+'@shopify/ui-extensions': patch
+---
+
+Deprecate renderMode on shipping option item

packages/ui-extensions/docs/surfaces/checkout/generated/generated_docs_data_v2.json

@@ -5854,7 +5854,8 @@
           "syntaxKind": "PropertySignature",
           "name": "renderMode",
           "value": "ShippingOptionItemRenderMode",
-          "description": "The render mode of this shipping option, indicating how the extension is displayed in the checkout UI."
+          "description": "The render mode of this shipping option, indicating how the extension is displayed in the checkout UI.",
+          "deprecationMessage": "Do not rely on render context. This target can render inside an overlay, so use inline UI instead of opening overlays such as modals."
         },
         {
           "filePath": "src/surfaces/checkout/api/shipping/shipping-option-item.ts",
@@ -5864,7 +5865,7 @@
           "description": "The shipping option that this extension is attached to. Use this to read the option's cost, carrier, delivery estimate, and other details.\n\nAvailable only on the corresponding item target. Shipping option item targets expose shipping option properties; pickup location item targets expose pickup location properties."
         }
       ],
-      "value": "export interface ShippingOptionItemApi {\n  /**\n   * The shipping option that this extension is attached to. Use this to read the option's cost, carrier, delivery estimate, and other details.\n   *\n   * Available only on the corresponding item target. Shipping option item\n   * targets expose shipping option properties; pickup location item targets\n   * expose pickup location properties.\n   */\n  target: SubscribableSignalLike<ShippingOption>;\n\n  /**\n   * Whether the buyer has selected the target shipping option. When `true`, the target option is the buyer's active choice. When `false`, the buyer has chosen a different shipping option.\n   *\n   * Available only on the corresponding item target. Shipping option item\n   * targets expose shipping option properties; pickup location item targets\n   * expose pickup location properties.\n   */\n  isTargetSelected: SubscribableSignalLike<boolean>;\n\n  /**\n   * The render mode of this shipping option, indicating how the extension is displayed in the checkout UI.\n   */\n  renderMode: ShippingOptionItemRenderMode;\n}"
+      "value": "export interface ShippingOptionItemApi {\n  /**\n   * The shipping option that this extension is attached to. Use this to read the option's cost, carrier, delivery estimate, and other details.\n   *\n   * Available only on the corresponding item target. Shipping option item\n   * targets expose shipping option properties; pickup location item targets\n   * expose pickup location properties.\n   */\n  target: SubscribableSignalLike<ShippingOption>;\n\n  /**\n   * Whether the buyer has selected the target shipping option. When `true`, the target option is the buyer's active choice. When `false`, the buyer has chosen a different shipping option.\n   *\n   * Available only on the corresponding item target. Shipping option item\n   * targets expose shipping option properties; pickup location item targets\n   * expose pickup location properties.\n   */\n  isTargetSelected: SubscribableSignalLike<boolean>;\n\n  /**\n   * The render mode of this shipping option, indicating how the extension is displayed in the checkout UI.\n   *\n   * @deprecated Do not rely on render context. This target can render inside an overlay, so use inline UI instead of opening overlays such as modals.\n   */\n  renderMode: ShippingOptionItemRenderMode;\n}"
     }
   },
   "ShippingOptionItemRenderMode": {
@@ -5879,10 +5880,11 @@
           "syntaxKind": "PropertySignature",
           "name": "overlay",
           "value": "boolean",
-          "description": "Whether the shipping option is rendered in an overlay. When `true`, the extension appears in a modal or sheet on top of the checkout page. When `false`, the extension renders inline within the shipping options list."
+          "description": "Whether the shipping option is rendered in an overlay. When `true`, the extension appears in a modal or sheet on top of the checkout page. When `false`, the extension renders inline within the shipping options list.",
+          "deprecationMessage": "Do not rely on render context. Use inline UI instead of opening overlays such as modals."
         }
       ],
-      "value": "export interface ShippingOptionItemRenderMode {\n  /**\n   * Whether the shipping option is rendered in an overlay. When `true`, the extension appears in a modal or sheet on top of the checkout page. When `false`, the extension renders inline within the shipping options list.\n   */\n  overlay: boolean;\n}"
+      "value": "export interface ShippingOptionItemRenderMode {\n  /**\n   * Whether the shipping option is rendered in an overlay. When `true`, the extension appears in a modal or sheet on top of the checkout page. When `false`, the extension renders inline within the shipping options list.\n   *\n   * @deprecated Do not rely on render context. Use inline UI instead of opening overlays such as modals.\n   */\n  overlay: boolean;\n}"
     }
   },
   "ShippingOptionListApi": {
@@ -168159,10 +168161,10 @@
       "returns": {
         "filePath": "src/surfaces/checkout/preact/shipping-option-target.ts",
         "description": "",
-        "name": "{\n  shippingOptionTarget: ShippingOption;\n  isTargetSelected: boolean;\n  renderMode: ShippingOptionItemRenderMode;\n}",
-        "value": "{\n  shippingOptionTarget: ShippingOption;\n  isTargetSelected: boolean;\n  renderMode: ShippingOptionItemRenderMode;\n}"
+        "name": "{\n  shippingOptionTarget: ShippingOption;\n  isTargetSelected: boolean;\n  /**\n   * @deprecated Do not rely on render context. This target can render inside an overlay, so use inline UI instead of opening overlays such as modals.\n   */\n  renderMode: ShippingOptionItemRenderMode;\n}",
+        "value": "{\n  shippingOptionTarget: ShippingOption;\n  isTargetSelected: boolean;\n  /**\n   * @deprecated Do not rely on render context. This target can render inside an overlay, so use inline UI instead of opening overlays such as modals.\n   */\n  renderMode: ShippingOptionItemRenderMode;\n}"
       },
-      "value": "export function useShippingOptionTarget(): {\n  shippingOptionTarget: ShippingOption;\n  isTargetSelected: boolean;\n  renderMode: ShippingOptionItemRenderMode;\n} {\n  const api = useApi<\n    | 'purchase.checkout.shipping-option-item.render-after'\n    | 'purchase.checkout.shipping-option-item.details.render'\n  >();\n  if (!api.target || api.isTargetSelected === undefined) {\n    throw new ExtensionHasNoTargetError(\n      'useShippingOptionTarget',\n      api.extension.target,\n    );\n  }\n\n  const shippingOptionTarget = useSubscription(api.target);\n  const isTargetSelected = useSubscription(api.isTargetSelected);\n  const renderMode = api.renderMode;\n\n  const shippingOption = useMemo(() => {\n    return {\n      shippingOptionTarget,\n      isTargetSelected,\n      renderMode,\n    };\n  }, [shippingOptionTarget, isTargetSelected, renderMode]);\n\n  return shippingOption;\n}"
+      "value": "export function useShippingOptionTarget(): {\n  shippingOptionTarget: ShippingOption;\n  isTargetSelected: boolean;\n  /**\n   * @deprecated Do not rely on render context. This target can render inside an overlay, so use inline UI instead of opening overlays such as modals.\n   */\n  renderMode: ShippingOptionItemRenderMode;\n} {\n  const api = useApi<\n    | 'purchase.checkout.shipping-option-item.render-after'\n    | 'purchase.checkout.shipping-option-item.details.render'\n  >();\n  if (!api.target || api.isTargetSelected === undefined) {\n    throw new ExtensionHasNoTargetError(\n      'useShippingOptionTarget',\n      api.extension.target,\n    );\n  }\n\n  const shippingOptionTarget = useSubscription(api.target);\n  const isTargetSelected = useSubscription(api.isTargetSelected);\n  const renderMode = api.renderMode;\n\n  const shippingOption = useMemo(() => {\n    return {\n      shippingOptionTarget,\n      isTargetSelected,\n      renderMode,\n    };\n  }, [shippingOptionTarget, isTargetSelected, renderMode]);\n\n  return shippingOption;\n}"
     }
   },
   "UseShopGeneratedType": {

packages/ui-extensions/docs/surfaces/checkout/reference/examples/purchase.checkout.shipping-option-item.render-after/default.example.tsx

@@ -1,4 +1,4 @@
-import {render, Fragment} from 'preact';
+import {render} from 'preact';
 
 import {useShippingOptionTarget} from '@shopify/ui-extensions/checkout/preact';
 
@@ -7,56 +7,22 @@ export default function extension() {
 }
 
 function Extension() {
-  const {
-    shippingOptionTarget,
-    isTargetSelected,
-    renderMode,
-  } = useShippingOptionTarget();
+  const {shippingOptionTarget, isTargetSelected} =
+    useShippingOptionTarget();
   const {
     cost: {amount, currencyCode},
     title,
   } = shippingOptionTarget;
 
-  // When the target is rendered inside the "More shipping options" modal for split shipping scenarios, `renderMode.overlay` is true. This check allows to render an alternative UI to avoid nested modals.
-  if (renderMode.overlay) {
-    return (
-      <s-text>
-        Shipping method: {title} is{' '}
-        {isTargetSelected ? '' : 'not'} selected.
-      </s-text>
-    );
-  }
-
-  // When the target is rendered inline for both split shipping and non-split shipping scenarios, a Modal can be rendered if desired.
   return (
-    <Fragment>
-      <s-link
-        command="--show"
-        commandFor="my-modal"
-      >
-        View details ({title} is{' '}
-        {isTargetSelected ? '' : 'not'} selected)
-      </s-link>
-      <s-modal
-        id="my-modal"
-        heading={`Shipping option: ${title}`}
-      >
-        <s-paragraph>
-          Cost:{' '}
-          {Intl.NumberFormat(undefined, {
-            style: 'currency',
-            currency: currencyCode,
-          }).format(amount)}
-        </s-paragraph>
-        <s-button
-          variant="primary"
-          command="--hide"
-          commandFor="my-modal"
-          slot="primary-action"
-        >
-          Close
-        </s-button>
-      </s-modal>
-    </Fragment>
+    <s-text>
+      Shipping method: {title} is{' '}
+      {isTargetSelected ? '' : 'not '}selected.
+      Cost:{' '}
+      {Intl.NumberFormat(undefined, {
+        style: 'currency',
+        currency: currencyCode,
+      }).format(amount)}
+    </s-text>
   );
 }

packages/ui-extensions/src/surfaces/checkout/api/shipping/shipping-option-item.ts

@@ -23,17 +23,22 @@ export interface ShippingOptionItemApi {
 
   /**
    * The render mode of this shipping option, indicating how the extension is displayed in the checkout UI.
+   *
+   * @deprecated Do not rely on render context. This target can render inside an overlay, so use inline UI instead of opening overlays such as modals.
    */
   renderMode: ShippingOptionItemRenderMode;
 }
 
 /**
  * The render mode of a shipping option.
+ *
  * @publicDocs
  */
 export interface ShippingOptionItemRenderMode {
   /**
    * Whether the shipping option is rendered in an overlay. When `true`, the extension appears in a modal or sheet on top of the checkout page. When `false`, the extension renders inline within the shipping options list.
+   *
+   * @deprecated Do not rely on render context. Use inline UI instead of opening overlays such as modals.
    */
   overlay: boolean;
 }

packages/ui-extensions/src/surfaces/checkout/preact/shipping-option-target.ts

@@ -17,6 +17,9 @@ import {useSubscription} from './subscription';
 export function useShippingOptionTarget(): {
   shippingOptionTarget: ShippingOption;
   isTargetSelected: boolean;
+  /**
+   * @deprecated Do not rely on render context. This target can render inside an overlay, so use inline UI instead of opening overlays such as modals.
+   */
   renderMode: ShippingOptionItemRenderMode;
 } {
   const api = useApi<