feat(checkout): ✨ Add parent/parentRelationship property to CartLines for Checkout. (#3072)

### Background

This PR adds parent/parentRelationship properties to CartLines for Checkout, enabling the representation of relationships between cart lines.  Follow up to the [private repo change](https://app.graphite.dev/github/pr/shop/world/62239).

### Solution

Added support for parent-child relationships between cart lines in the Checkout API:

1. Added a new `CartLineParentRelationship` interface that contains parent line information
2. Added the `parentRelationship` property to the `CartLine` interface
3. Added optional `parent` property to `CartLineAddChange` and `CartLineUpdateChange` interfaces to allow setting parent relationships when adding or updating cart lines
4. Exported the new `CartLineParentRelationship` type

These changes enable extensions to work with hierarchical cart line structures, such as bundles or add-ons that are associated with a parent product.

### 🎩

- Test adding a cart line with a parent relationship
- Test updating a cart line to associate it with a parent
- Verify parent relationships are correctly displayed in the UI

### Checklist

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

Author: patrickDouglas

.changeset/violet-eggs-deliver.md

@@ -0,0 +1,5 @@
+---
+'@shopify/ui-extensions': minor
+---
+
+Add parent/parentRelationship property to CartLines for Checkout.

packages/ui-extensions/src/surfaces/checkout.ts

@@ -31,6 +31,7 @@ export type {
   AppMetafieldEntryTarget,
   AppMetafieldEntry,
   CartLine,
+  CartLineParentRelationship,
   PaymentOption,
   SelectedPaymentOption,
   CartDiscountCode,

packages/ui-extensions/src/surfaces/checkout/api/checkout/checkout.ts

@@ -183,6 +183,11 @@ export interface CartLineAddChange {
    * with.
    */
   sellingPlanId?: SellingPlan['id'];
+
+  /**
+   * The identifier for the associated parent cart line.
+   */
+  parent?: {lineId: string} | {merchandiseId: string};
 }
 
 export interface CartLineRemoveChange {
@@ -236,6 +241,11 @@ export interface CartLineUpdateChange {
    * with or `null` to remove the the product from the selling plan.
    */
   sellingPlanId?: SellingPlan['id'] | null;
+
+  /**
+   * The identifier for the associated parent cart line.
+   */
+  parent?: {lineId: string} | {merchandiseId: string};
 }
 
 export type DiscountCodeChange =

packages/ui-extensions/src/surfaces/checkout/api/standard/standard.ts

@@ -977,6 +977,26 @@ export interface CartLine {
    * Sub lines of the merchandise line. If no sub lines are present, this will be an empty array.
    */
   lineComponents: CartLineComponentType[];
+
+  /**
+   * The relationship details between cart lines.
+   */
+  parentRelationship: CartLineParentRelationship | null;
+}
+export interface CartLineParentRelationship {
+  /**
+   * The parent cart line that a cart line is associated with.
+   */
+  parent: {
+    /**
+     * These line item IDs are not stable at the moment, they might change after
+     * any operations on the line items. You should always look up for an updated
+     * ID before any call to `applyCartLinesChange` because you'll need the ID to
+     * create a `CartLineChange` object.
+     * @example 'gid://shopify/CartLine/123'
+     */
+    id: string;
+  };
 }
 
 type CartLineComponentType = CartBundleLineComponent;