``` `timer` * **타입**: `string` * **설명**: 문자열로 형식화된 현재 타이머 값 * **사용법**: 커스텀 공지 구현에서 카운트다운 타이머를 표시해요 ```

Time remaining: {props.timer}

``` `shouldUseTimer` * **타입**: `boolean` * **설명**: 이 공지에서 타이머 기능이 활성화되어 있는지를 나타내요 * **사용법**: 타이머 관련 콘텐츠와 컨트롤을 조건부로 렌더링해요 ```

{props.shouldUseTimer && ( {props.timer} )}

``` `isTimerExpiredAndShouldHide` * **타입**: `boolean` * **설명**: 타이머가 만료되어 공지를 숨겨야 하는지를 나타내요 * **사용법**: 타이머 상태에 따라 공지 전체의 표시 여부를 제어해요 ```

{!props.isTimerExpiredAndShouldHide && (

{props.timer}

)}

```

## 티어형 리워드

Rewards 모듈을 사용하면 마일스톤 추적, 진행 상황 시각화, 리워드 메시지 같은 필수 리워드 기능을 유지하면서 리워드 진행 표시를 원하는 디자인으로 커스터마이징할 수 있어요.

### 사용 가능한 Props - **Full template**

`rewardsMessageHtml` * **타입**: `string` * **설명**: 리워드 메시지의 HTML 콘텐츠 * **사용법**: 커스텀 구현에서 서식이 적용된 리워드 메시지를 표시해요 ```

``` `milestonesCompleted` * **타입**: `number` * **설명**: 완료된 마일스톤 수 * **사용법**: 완료 수를 표시하거나 완료 비율을 계산해요 ```

{Math.round((props.milestonesCompleted / props.milestonesData.milestonesToRender.length) * 100)}% Complete

``` `milestonesData` * 타입: ``` { milestonesToRender: { id: string; label: string; icon: React.ReactElement; isCompleted: boolean; positionPercent: number; }[]; progressPercent: number; showMilestones: boolean; settings: { iconContainerSize: string; iconAlignment: string; labelAlignment: string; hideLabel: boolean; }; } ``` * **설명**: 리워드 시스템의 전체 마일스톤 구성 및 진행 데이터 * **사용법**: 마일스톤 정보, 진행 비율, 표시 설정에 접근해요 * **속성**: * `milestonesToRender`: 완료 상태와 위치 정보가 포함된 마일스톤 객체 배열 * `progressPercent`: 현재 진행률(0-100 백분율) * `showMilestones`: 마일스톤 마커 표시 여부 * `settings`: 마일스톤 표시를 위한 시각적 구성

## 할인

Discounts 모듈은 규칙 관리, 섹션 표시, 리워드 표시 같은 필수 기능을 유지하면서 직접 디자인할 수 있도록 커스텀 템플릿을 지원해요. 커스텀 템플릿의 내부 모듈 타입 식별자는 기존 커스텀 템플릿 코드와의 하위 호환성을 위해 `TRIGGERED_REWARDS`예요.

### **사용 가능한 Props - Full template**

`rules` * **타입**: ``` { id: string; title: string; description: string; conditionsMet: boolean; }[] ``` * **설명**: 현재 활성화된 Discount 규칙 배열 * **사용법**: 사용 가능한 리워드와 제목, 설명, 각 규칙의 조건 충족 여부를 표시해요 * **속성**: * `id`: 리워드 규칙의 고유 식별자 * `title`: Discount 규칙의 제목 * `description`: 리워드 규칙의 설명 * `conditionsMet`: 규칙의 조건이 현재 카트에서 충족되었는지 여부. 이를 사용해 "X를 잠금 해제했어요" 대 "X를 잠금 해제하려면 \$Y 더 지출하세요" UX 패턴을 만들 수 있어요 ```

{props.rules.map((rule) => (

{rule.title}

{rule.conditionsMet ? "Reward unlocked!" : rule.description}

))}

``` `showSection` * **타입**: `boolean` * **설명**: Discounts 섹션을 표시할지 여부를 나타내요 * **사용법**: Discounts 모듈 전체의 표시 여부를 제어해요 ```

{props.showSection && (

Available Rewards...

)}

``` `onToggleSection` * **타입**: `() => void` * **설명**: Discounts 섹션의 표시 상태를 전환하는 콜백 함수 * **사용법**: 버튼이나 인터랙티브 요소에 연결해 사용자가 리워드 섹션을 표시/숨김할 수 있도록 해요 ``` ```

## 추천

Recommendation 모듈을 사용하면 옵션(variant) 선택, 카트 담기 액션, 상품 정보 표시 같은 필수 이커머스 기능을 유지하면서 업셀 상품 표시를 원하는 디자인으로 커스터마이징할 수 있어요.

### **사용 가능한 Props - Recommendation tile template**

*추천 타일 템플릿은 Upsells 모듈의 [업셀 타일 템플릿과 동일한 prop 인터페이스](#available-props-upsell-tile-template)를 공유해요. 사용 가능한 모든 props, 타입, 사용 예시는 아래 Upsells 모듈 섹션에 문서화되어 있어요.*

## 카트 상품

Cart Items 모듈을 사용하면 필수 이커머스 기능을 유지하면서 카트 상품 표시를 원하는 디자인으로 커스터마이징할 수 있어요. 이 모듈은 카트 상품 표시의 다양한 측면을 위한 각각의 전용 props를 가진 여러 템플릿 유형을 제공해요. **카트 담기 또는 카트 업데이트 중 로딩 표시기 표시하기:** 표준 Cart Items 모듈에는 내장된 "카트에 추가 중" 스피너가 없어요. 상품이 추가되는 동안이나 카트 작업이 진행 중일 때 로딩 상태를 표시하고 싶다면, Product tile 템플릿을 사용해 `isLoading`과 `loadingOperation` props(아래에 문서화됨)를 읽어 스피너나 오버레이를 조건부로 렌더링하세요. 커스텀 템플릿에는 개발 경험이 필요해요 — 이 페이지 상단의 공지를 참고하세요.

### **사용 가능한 Props - Product tile template**

**참고:** *Product Tile* 템플릿을 활성화하면 **Variant template**, **Properties template**, **Bundle template**, **Price template**을 포함한 이 모듈의 다른 모든 템플릿이 재정의돼요.\ 해당 템플릿 중 하나에서 커스텀 코드를 사용하려면 ***반드시*** *Product Tile 템플릿을 꺼야 해요.* 이미지, 옵션, 할인가, 수량 선택기, 구독 버튼이 있는 카트 상품 타일

이미지, 옵션, 할인가, 수량 선택기, 구독 버튼이 있는 카트 상품 타일

`title` * **타입**: `string` * **설명**: 상품 제목/이름 * **사용법**: 카트 상품에 주요 상품명을 표시해요 `variant` * **타입**: `React.ReactNode` * **설명**: 미리 렌더링된 옵션(variant) 정보 컴포넌트 * **사용법**: 옵션 세부 정보를 React 컴포넌트로 표시해요 `properties` * **타입**: `React.ReactNode` * **설명**: 미리 렌더링된 상품 속성 컴포넌트 * **사용법**: 상품 속성과 구독 정보를 React 컴포넌트로 표시해요 `bundle` * **타입**: `React.ReactNode` * **설명**: 미리 렌더링된 번들 세부 정보 컴포넌트 * **사용법**: 번들 정보를 React 컴포넌트로 표시해요 `compareAtPrice` * **타입**: `string | undefined` * **설명**: 형식화된 비교 가격(원래 가격) * **사용법**: 할인 상품의 원래 가격을 표시해요 `price` * **타입**: `string` * **설명**: 형식화된 현재 가격 * **사용법**: 현재 상품 가격을 표시해요 `savings` * **타입**: `string | undefined` * **설명**: 형식화된 절약 금액 * **사용법**: 고객이 얼마나 절약하는지 표시해요 `imageUrl` * **타입**: `string | undefined` * **설명**: 상품 이미지 URL * **사용법**: 상품 이미지를 표시해요 `productUrl` * **타입**: `string | undefined` * **설명**: 상품 페이지 URL * **사용법**: 상품 상세 페이지로 링크해요 `quantity` * **타입**: `number` * **설명**: 카트에 담긴 현재 상품 수량 * **사용법**: 상품 수량을 표시하고 관리해요 `showQuantitySelector` * **타입**: `boolean` * **설명**: 수량 컨트롤 표시 여부 * **사용법**: 수량 선택기를 조건부로 표시해요 `discountCodes` * **타입**: `string[] | undefined` * **설명**: 이 상품에 적용된 할인 코드 배열 * **사용법**: 상품별 할인을 표시해요 `subscription` * **타입**: ``` { subscriptionUpgradeData: { buttonText: string; defaultSellingPlanId: number; } | null; sellingPlansData: { sellingPlanGroups: { name: string; selling_plans: { id: number; name: string; }[]; }[] | null; activeSellingPlanId: string; oneTimePurchaseText: string | null; } | null; upgradeSellingPlan: (item: CartItem, sellingPlanId: number) => void; changeSellingPlan: (item: CartItem, value: string) => void; getSellingPlanGroupText: (groupName: string, planName: string) => string; } ``` * **설명**: 업그레이드 데이터, 판매 플랜, 핸들러 함수가 포함된 완전한 구독 관리 객체 * **사용법**: 구독 기능을 관리해요 * subscription 객체에는 다음이 포함돼요: * **subscriptionUpgradeData**: 업그레이드 정보(업그레이드가 없으면 null) * `buttonText`: 업그레이드 버튼 텍스트 * `defaultSellingPlanId`: 업그레이드용 기본 판매 플랜 ID * **sellingPlansData**: 사용 가능한 판매 플랜 옵션(플랜이 없으면 null) * `sellingPlanGroups`: 판매 플랜이 포함된 플랜 그룹 배열 * `activeSellingPlanId`: 현재 선택된 판매 플랜 ID * `oneTimePurchaseText`: 일회성 구매 옵션 텍스트(사용 불가 시 null) * **upgradeSellingPlan**: 특정 판매 플랜으로 업그레이드하는 함수 * **changeSellingPlan**: 현재 판매 플랜을 변경하는 함수 * **getSellingPlanGroupText**: 판매 플랜 표시 텍스트를 형식화하는 유틸리티 함수 `onIncrease` * **타입**: `() => void` * **설명**: 상품 수량을 늘리는 함수 * **사용법**: 수량 증가 액션을 처리해요 `onDecrease` * **타입**: `() => void` * **설명**: 상품 수량을 줄이는 함수 * **사용법**: 수량 감소 액션을 처리해요 `onDeleteProduct` * **타입**: `() => void` * **설명**: 카트에서 상품을 제거하는 함수 * **사용법**: 상품 제거를 처리해요 `onQuantityChange` * **타입**: `(quantity: string) => void` * **설명**: 직접 수량 입력을 처리하는 함수 * **사용법**: 수동 수량 변경을 처리해요 `handleInputChange` * **타입**: `(e: React.ChangeEvent) => void` * **설명**: 수량 필드의 입력 변경 핸들러 * **사용법**: 수량 입력 필드 변경을 처리해요 `replaceItemWithVariant` * **타입**: `(variantId: string) => Promise<{ success: boolean }>` * **설명**: 상품을 다른 옵션(variant)으로 교체하는 함수 * **사용법**: 옵션 전환을 처리해요 `isLoading` * **타입**: `boolean` * **설명**: 카트 작업의 로딩 상태 * **사용법**: 로딩 표시기를 표시해요 `loadingOperation` * **타입**: `'increase' | 'decrease' | 'inputChange' | 'remove' | 'subscription' | undefined` * **설명**: 현재 로딩 중인 특정 작업 * **사용법**: 작업별 로딩 상태를 표시해요 `setLoadingOperation` * **타입**: `(op: "increase" | "decrease" | "inputChange" | "remove" | "subscription" | undefined) => void` * **설명**: 로딩 작업 상태를 설정하는 함수 * **사용법**: 다양한 작업의 로딩 상태를 관리해요 `rawItem` * **타입**: `CartItem`([아래](#cartitem-object-properties)의 `CartItem` 타입 참고) * **설명**: 모든 정보를 담고 있는 원시 카트 상품 데이터

### **사용 가능한 Props - Variant template**

`item` * **타입**: `CartItem`([아래](#cartitem-object-properties)의 `CartItem` 타입 참고) * **설명**: 옵션(variant) 정보가 포함된 원시 카트 상품 데이터 * **사용법**: 카트 상품에서 옵션 세부 정보에 접근해요

### **사용 가능한 Props - Properties template**

`productProperties` * **타입**: `{ key: string; value: string; isUrl?: boolean; }[]` * **설명**: 상품 속성 배열(커스텀 필드, 라인 아이템 속성) `subscriptionLabel` * **타입**: `string | undefined` * **설명**: 구독 정보 레이블

### **사용 가능한 Props - Bundle template**

`getSizedImageUrl` * **타입**: `getSizedImageUrl: ({ src, width, height }: SizedImageParams) => string` * **설명**: 적절한 크기의 이미지 URL을 가져오는 유틸리티 함수 `item` * **타입**: ``` { itemComponents: { quantity: number; image: { url: string; height: number | null; width: number | null; alt: string; }; product: { title: string; has_only_default_variant: boolean; }; variantTitle: string; }[]; variantTitle: string | undefined; hasComponents: boolean; } ``` * **설명**: 구성 요소를 포함한 번들 상품 정보. `itemComponents`는 구성 요소 객체 배열이에요 — 각 번들 구성 요소를 렌더링하려면 배열을 순회(map)하세요. `showDetailsText` * **타입**: `string | undefined` * **설명**: "세부 정보 표시" 액션 텍스트 * **사용법**: 펼치기 버튼 텍스트를 표시해요 `hideDetailsText` * **타입**: `string | undefined` * **설명**: "세부 정보 숨기기" 액션 텍스트 `isExpanded` * **타입**: `boolean` * **설명**: 번들 세부 정보가 펼쳐져 있는지 여부 `toggleCollapsible` * **타입**: `() => void` * **설명**: 번들 세부 정보 표시를 전환하는 함수 * **사용법**: 펼치기/접기 액션을 처리해요 `chevronDownIconComponent` * **타입**: `React.ReactElement` * **설명**: 펼치기/접기용으로 미리 렌더링된 셰브론 아이콘 * **사용법**: 일관된 펼치기/접기 표시기를 표시해요

### **사용 가능한 Props - Price template**

`compareAtPrice` * **타입**: `string | undefined` * **설명**: 형식화된 비교 가격(원래 가격) * **사용법**: 할인 상품의 원래 가격을 표시해요 `price` * **타입**: `string` * **설명**: 형식화된 현재 가격 * **사용법**: 현재 상품 가격을 표시해요 `savings` * **타입**: `string | undefined` * **설명**: 형식화된 절약 금액 * **사용법**: 고객이 얼마나 절약하는지 표시해요

### **CartItem 객체 속성**

`CartItem` 객체에는 카트 라인 아이템에 대한 모든 세부 정보가 담겨 있어요. 이 객체는 Product Tile 템플릿에서는 props.rawItem으로, Variant 템플릿에서는 props.item으로 사용할 수 있어요.

#### **핵심 식별 정보**

* `key (string)` - 이 카트 상품의 고유 식별자. * `id (number)` - 옵션(variant) ID(레거시 필드, 대신 variant\_id 사용) * `variant_id (number)` - 이 상품의 Shopify 옵션 ID * `product_id (number)` - Shopify 상품 ID * `lineIdxFrom1 (number)` - 수정 전 원래 카트에서 이 상품의 1부터 시작하는 인덱스

#### **상품 정보**

* `title (string)` - 라인 아이템 제목(일반적으로 옵션 제목) * `product_title (string)` - 주요 상품 제목 * `handle (string)` - 상품 URL 핸들(예: "camp-stool") * `vendor (string)` - 상품 공급업체/브랜드명 * `product_type (string)` - 세금 목적의 상품 카테고리/유형 * `sku (string)` - 재고 관리 단위(SKU) 식별자 * `product_description (string)` - 전체 상품 설명 * `product_has_only_default_variant (boolean)` - 상품에 옵션이 하나뿐인지 여부

#### **가격(모든 가격은 센트 단위)**

* `quantity (number)` - 카트에 담긴 이 상품의 수량 * `price (number)` - 할인 전 단가 * `original_price (number)` - price와 동일 * `discounted_price (number)` - 상품 수준 할인 후 단가 * `compare_at_price (number | null)` - 비교 가격(MSRP). 참고: 이 필드는 Shopify 카트 API에서 제공하는 것이 아니라 Upcart가 추가한 필드예요 * `final_line_price (number)` - 상품 수준 할인 후 총 가격(수량 × discounted\_price) * `original_line_price (number)` - 할인 전 총 가격(수량 × price) * `line_price (number)` - 모든 할인 적용 후 총 가격 * `final_price (number)` - **지원 중단됨** - 상품 할인 후 단가(수량 미반영) * `total_discount (number)` - line\_level\_total\_discount와 동일 * `line_level_total_discount (number)` - 이 라인 아이템에 적용된 총 할인 금액

#### **미디어 및 URL**

* `image (string)` - 기본 상품 이미지 URL * `url (string)` - 상품 페이지의 상대 URL 경로(예: "/products/camp-stool?variant=42789611372803") * `featured_image (object | null)` - 대표 이미지 세부 정보: * `alt (string)` - 이미지 대체 텍스트 * `aspect_ratio (number)` - 이미지 가로세로 비율 * `height (number)` - 이미지 높이(픽셀) * `url (string)` - 이미지 URL * `width (number)` - 이미지 너비(픽셀)

#### **옵션(Variant) 정보**

* `variant_title (string | null)` - 옵션 제목(예: "Large / Red") * `variant_options (string[])` - 옵션 값 배열 * `options_with_values (Array)` - 상세 옵션 정보: * `name (string)` - 옵션 이름(예: "Size") * `value (string)` - 옵션 값(예: "Large") * `untranslated_product_title (string | undefined)` - 번역 전 원래 상품 제목(카트 변경 응답에서만 제공) * `untranslated_variant_title (string | undefined)` - 번역 전 원래 옵션 제목(카트 변경 응답에서만 제공)

#### **커스텀 속성 및 메타데이터**

* `properties (Record | null)` - 커스텀 라인 아이템 속성이며, 라인에 속성이 없으면 `null`이에요 — 키를 읽기 전에 확인하세요. 키가 `__`로 시작하는 속성은 항상 고객에게 숨겨지고, 단일 `_`로 시작하는 키는 **Hide properties starting with single underscore "\_"** 카트 설정이 켜져 있을 때 함께 숨겨져요. * `gift_card (boolean)` - 이 상품이 기프트 카드인지 여부 * `taxable (boolean)` - 이 상품이 과세 대상인지 여부 * `requires_shipping (boolean)` - 이 상품이 배송을 필요로 하는지 여부 * `grams (number)` - 상품 무게(그램)

#### **할인 및 프로모션**

* `discounts (Array)` - 간소화된 할인 정보: * `amount (number)` - 할인 금액(센트) * `title (string)` - 할인 제목/이름 * `line_level_discount_allocations (Array)` - 상세 할인 할당 정보: * `amount (number)` - 할인 금액(센트) * `discount_application (object)` - 전체 할인 적용 세부 정보: * `allocation_method (string)` - 할인 할당 방식 * `created_at (string)` - 할인 생성 시점 * `description (string | null)` - 할인 설명 * `key (string)` - 할인 키 식별자 * `target_selection (string)` - 할인 대상 선택 * `target_type (string)` - 대상 유형 * `title (string)` - 할인 제목 * `total_allocated_amount (number)` - 총 할당 금액 * `type ('discount_code' | '')` - 할인 유형(자동 할인은 빈 문자열) * `value (string)` - 할인 값 * `value_type (string)` - 값 적용 방식

#### **번들 상품**

* `has_components (boolean | undefined)` - 이 상품이 다른 상품을 포함하는 번들인지 여부(GET 카트 응답에서만 제공) * `item_components (Array | null | undefined)` - 번들 구성 요소 세부 정보: * `quantity (number)` - 이 구성 요소의 수량 * `image (object)` - 구성 요소 이미지: * `url (string)` - 이미지 URL * `height (number | null)` - 이미지 높이 * `width (number | null)` - 이미지 너비 * `alt (string)` - 대체 텍스트 * `product (object)` - 구성 요소 상품 정보: * `title (string)` - 상품 제목 * `has_only_default_variant (boolean)` - 상품에 기본 옵션만 있는지 여부 * `variantTitle (string)` - 구성 요소 옵션 제목

#### **비즈니스 규칙**

* `quantity_rule (object | undefined)` - 수량 제약(GET 카트 응답에서만 제공): * `min (number)` - 최소 허용 수량 * `max (number | null)` - 최대 허용 수량(null = 제한 없음) * `increment (number)` - 수량 증가 단위

#### **구독 정보**

* `selling_plan_allocation (object | undefined)` - 구독/판매 플랜 세부 정보: * `price (number)` - 구독 가격(센트) * `compare_at_price (number | null)` - 구독 비교 가격 * `per_delivery_price (number)` - 배송당 가격 * `selling_plan (object)` - 판매 플랜 세부 정보: * `id (number)` - 판매 플랜 ID * `name (string)` - 플랜 이름 * `description (string)` - 플랜 설명 * `options (Array)` - 플랜 옵션: * `name (string)` - 옵션 이름 * `position (number)` - 옵션 위치 * `value (string)` - 옵션 값 * `recurring_deliveries (boolean)` - 플랜에 반복 배송이 있는지 여부

#### **통합 메타데이터**

* `__appIntegrated (object | undefined)` - 서드파티 앱 통합 데이터: * `app ('stay.ai')` - 통합된 앱 식별자 * `bundleRole ('parent' | 'child')` - 번들 구조에서의 역할

## 업셀

Upsells 모듈을 사용하면 옵션(variant) 선택, 카트 담기 액션, 상품 정보 표시 같은 필수 이커머스 기능을 유지하면서 업셀 상품 표시를 원하는 디자인으로 커스터마이징할 수 있어요.

### **사용 가능한 Props - Upsell tile template**

`itemUrl` * **타입**: `string` * **설명**: 상품 페이지의 URL * **사용법**: 사용자 탐색 향상을 위해 상품 상세 페이지 링크를 만들어요 ```

``` `imageUrl` * **타입**: `string | undefined` * **설명**: 상품 이미지의 URL * **사용법**: 커스텀 업셀 구현에서 상품 이미지를 표시해요 * **폴백**: 플레이스홀더 이미지로 undefined 값을 안전하게 처리하세요 `description` * **타입**: `string` * **설명**: 상품 설명 * **사용법**: 커스텀 업셀 구현에서 상품 설명을 표시해요 `altText` * **타입**: `string` * **설명**: 접근성을 위한 상품 이미지 대체 텍스트 * **사용법**: 스크린 리더 지원을 제공하고 접근성 준수를 개선해요 ``` {props.altText}

``` `productId` * **타입**: `string` * **설명**: 상품의 고유 식별자 * **사용법**: 상품 추적, 분석 구현 또는 카트 담기 기능에 사용해요 `productTitle` * **타입**: `string` * **설명**: 상품의 제목/이름 * **사용법**: 커스텀 업셀 구현에서 상품명을 표시해요 ```

{props.productTitle}

``` `oldPrice` & `newPrice` * **타입**: `string | null` (oldPrice), `string` (newPrice) * **설명**: 형식화된 비교 가격과 현재 가격 * **사용법**: 세일 표시와 함께 가격 정보를 표시해요 `isSingleVariant` * **타입**: `boolean` * **설명**: 상품에 옵션(variant)이 하나뿐인지 나타내요 * **사용법**: 옵션 선택 UI 요소를 조건부로 렌더링해요 `productOptions` * **타입**: `{ name: string; position: 1 | 2 | 3; values: string[]; }[]` * **설명**: 사용 가능한 모든 선택지를 포함한 전체 상품 옵션 구성 * **사용법**: 고급 옵션 선택 UI를 위한 상세 상품 옵션 정보에 접근해요 `variantOptions` * **타입**: `{ label: string; value: string }[]` * **설명**: 상품에서 사용 가능한 옵션(variant) 목록 * **사용법**: 옵션 선택 드롭다운이나 버튼을 만들어요 * **구조**: 각 옵션에는 표시 레이블과 고유 값 식별자가 포함돼요 `selectedVariantId` & `selectedVariantLabel` * **타입**: string (selectedVariantId), string | undefined (selectedVariantLabel) * **설명**: 현재 선택된 옵션 ID와 표시 레이블 * **사용법**: 선택된 옵션 정보를 추적하고 표시해요 `onVariantChange` * **타입**: `(variantId: string) => void` * **설명**: 옵션 선택 변경을 처리하는 함수 * **사용법**: 사용자가 선택할 때 선택된 옵션을 업데이트해요 `onAddClick` * **타입**: `(productId: string, variantId?: string) => void` * **설명**: 상품을 카트에 추가하는 것을 처리하는 함수 * **사용법**: 올바른 상품 및 옵션 식별과 함께 카트 담기 기능을 구현해요 ``` ``` `rating` & `reviewCount` * **타입**: `number | undefined` (rating), `string | undefined` (reviewCount) * **설명**: 상품 평점과 형식화된 리뷰 수 텍스트 * **사용법**: 사회적 증거와 상품 품질 지표를 표시해요 `addLoading` & `addButtonText` * **타입**: `boolean` (addLoading), `string` (addButtonText) * **설명**: 카트 담기 액션의 로딩 상태와 버튼 텍스트 * **사용법**: 카트 작업 중 사용자 피드백을 제공하고 버튼 텍스트를 커스터마이징해요 `cartItemsCount` * **타입**: `number` * **설명**: 현재 카트에 담긴 상품 수 * **사용법**: 카트 상태를 표시하거나 카트 기반 로직을 구현해요

## 추가 노트

Notes 모듈을 사용하면 펼침 섹션, 텍스트 입력 처리, 로딩 상태 같은 필수 노트 기능을 유지하면서 카트 노트 기능을 원하는 디자인으로 커스터마이징할 수 있어요.

### **사용 가능한 Props - Full template**

`cartNote` * **타입**: `string` * **설명**: 고객이 입력한 현재 카트 노트 내용 * **사용법**: 커스텀 구현에서 카트 노트 텍스트를 표시하고 관리해요 ```

```

`notesPlaceholder`

* **타입**: `string`

* **설명**: 노트 입력 필드의 플레이스홀더 텍스트

* **사용법**: 노트에 어떤 내용을 포함할지 고객에게 안내해요

```
<textarea  
  placeholder={props.notesPlaceholder}  
  ...  
/>
```

`notesTitle`

* **타입**: `string`

* **설명**: 노트 섹션의 제목/헤더 텍스트

* **사용법**: 커스텀 노트 구현에서 섹션 제목을 표시해요

```
<h3 className="notes-title" dangerouslySetInnerHTML={{ __html: props.notesTitle }} />
```

`chevronDownIconComponent`

* **타입**: `React.ReactElement`

* **설명**: 펼치기/접기 기능을 위한 미리 렌더링된 셰브론 아이콘 컴포넌트

* **사용법**: 커스텀 구현에서 일관된 펼치기/접기 표시기를 표시해요

`loadingIndicatorComponent`

* **타입**: `React.ReactElement | null`

* **설명**: 비동기 작업을 위한 미리 렌더링된 로딩 표시기 컴포넌트

* **사용법**: 노트 저장 작업 중 로딩 상태를 표시해요

`handleCartNoteChange`

* **타입**: `(newCartNote: string) => void`

* **설명**: 카트 노트 내용 변경을 처리하는 함수

* **사용법**: 사용자가 텍스트를 수정할 때 카트 노트를 업데이트해요

`isExpanded`

* **타입**: `boolean`

* **설명**: 노트 섹션이 현재 펼쳐져 있는지 나타내요

* **사용법**: 노트 입력 영역의 표시 여부를 제어해요

`toggleCollapsible`

* **타입**: `() => void`

* **설명**: 노트 섹션의 펼침/접힘 상태를 전환하는 함수

* **사용법**: 버튼이나 인터랙티브 요소에 연결해 섹션 표시를 제어해요

***

<div id="footer-section">
  ## Footer 섹션
</div>

Addons 모듈을 사용하면 상품 정보 표시, 가격, 토글 컨트롤, 통화 형식 같은 필수 이커머스 기능을 유지하면서 애드온 상품 표시를 원하는 디자인으로 커스터마이징할 수 있어요.

<div id="available-props-full-template-6">
  ### **사용 가능한 Props - Full template**
</div>

`addonProduct`

* **타입**:

```
  {  
    product: {  
      id: number;  
      title: string;  
      description: string;  
    };  
    variant: {  
      id: number;  
      price: number;  
      compare_at_price: number | null;  
    };  
    image: {  
      src: string;  
      alt: string;  
    };  
  }
  ```

* **설명**: 상품 세부 정보, 옵션 가격, 이미지 데이터를 포함한 완전한 애드온 상품 정보

* **사용법**: 애드온 상품 표시에 필요한 모든 상품 정보에 접근해요

* **구조**: 포괄적인 상품 데이터가 담긴 중첩된 product, variant, image 객체를 포함해요

* **Product 객체 속성** `addonProduct.product`

* **id**: 상품의 고유 숫자 식별자
    * **title**: 애드온 상품의 표시 이름
    * **description**: 상품의 HTML 설명 콘텐츠
  * **Variant 객체 속성**

* **id**: 옵션의 고유 숫자 식별자
    * **price**: 현재 가격(센트)
    * **compare\_at\_price**: 원래 가격(센트, 비교 가격이 없으면 null)
  * **Image 객체 속성**

* **src**: 상품 이미지의 URL
    * **alt**: 이미지 대체 텍스트(접근성용)

`toggle`

* **타입**:

```
  {  
    state: 'enabled' | 'disabled' | 'loading';  
    handleEnable: () => void;  
    handleDisable: () => void;  
  } | null
  ```

* **설명**: 애드온 활성화/비활성화를 위한 토글 컨트롤 상태와 핸들러

* **사용법**: 애드온 선택을 위한 인터랙티브 토글 기능을 구현해요

* **상태**: enabled, disabled, loading 세 가지 상태가 가능해요

* **핸들러**: 활성화와 비활성화 액션을 위한 별도의 함수

`moneyFormat`

* **타입**: `string`

* **설명**: 가격 형식화에 사용되는 통화 형식 문자열

* **사용법**: 일관된 통화 표시를 위해 formatMoney 함수에 전달하세요

`formatMoney`

* **타입**:

```
  (options: {  
    cents: string | number;  
    format?: string;  
    shouldRemoveHTML?: boolean;  
  }) => string
  ```

* **설명**: 통화 값을 형식화하는 유틸리티 함수

* **사용법**: 스토어 통화 설정에 맞게 가격을 일관되게 형식화해요

* **매개변수**: 센트 값, 선택적 형식 문자열, HTML 제거 옵션을 받아요

Discount Code 모듈을 사용하면 코드 검증, 폼 제출, 사용자 피드백 같은 필수 이커머스 기능을 유지하면서 할인 코드 입력 기능을 원하는 디자인으로 커스터마이징할 수 있어요.

<div id="available-props-full-template-7">
  ### **사용 가능한 Props - Full template**
</div>

`indicator`

* **타입**: `'validating' | 'invalid' | 'none'`

* **설명**: 할인 코드 입력의 현재 검증 상태

* **사용법**: 검증 상태에 따라 적절한 UI 피드백을 표시해요

* **상태**:

* `validating`: 코드가 처리/검증 중이에요
  * `invalid`: 코드 검증에 실패했어요
  * `none`: 검증 상태 없음(기본/대기)

`discountCodeInput`

* **타입**: `string`

* **설명**: 할인 코드 입력 필드의 현재 값

* **사용법**: 사용자가 입력한 할인 코드 텍스트를 표시하고 관리해요

```
<input  
  type="text"  
  value={props.discountCodeInput}  
  onChange={(e) => props.setDiscountCodeInput(e.target.value)}  
  ...  
/>
```

`discountCodePlaceholder`

* **타입**: `string`

* **설명**: 할인 코드 입력 필드의 플레이스홀더 텍스트

* **사용법**: 입력란에 무엇을 입력할지 사용자에게 안내해요

`discountCodeButtonText`

* **타입**: `string`

* **설명**: 적용/제출 버튼에 표시할 텍스트

* **사용법**: 할인 코드 제출 버튼 텍스트를 커스터마이징해요

`setDiscountCodeInput`

* **타입**: `(value: string | ((prev: string) => string)) => void`

* **설명**: 할인 코드 입력 값을 업데이트하는 함수

* **사용법**: 할인 코드 필드의 사용자 입력 변경을 처리해요

`handleSubmit`

* **타입**: `(e: React.FormEvent<HTMLFormElement>) => void`

* **설명**: 할인 코드 적용을 위한 폼 제출을 처리하는 함수

* **사용법**: 할인 코드 검증 및 적용을 처리해요

* **이벤트**: 폼 제출 이벤트를 처리해요

```
<form onSubmit={props.handleSubmit} >  
  <div className="input-group">  
    <input  
      type="text"  
      value={props.discountCodeInput}  
      onChange={(e) => props.setDiscountCodeInput(e.target.value)}  
      placeholder={props.discountCodePlaceholder}  
    />   
    <button   
      type="submit"  
      disabled={props.indicator === 'validating' || !props.discountCodeInput.trim()}  
    >  
      {props.discountCodeButtonText}  
    </button>  
  </div>  
</form>
```

Cart Summary 모듈을 사용하면 할인 관리, 절약 금액 계산, 가격 투명성 같은 필수 이커머스 기능을 유지하면서 카트 요약 및 할인 표시를 원하는 디자인으로 커스터마이징할 수 있어요.

<div id="available-props-full-template-8">
  ### **사용 가능한 Props - Full template**
</div>

`totalSavingsText`

* **타입**: `string`

* **설명**: 총 절약 금액 섹션의 텍스트 레이블

* **사용법**: 커스텀 카트 요약 구현에서 절약 레이블을 표시해요

`discountApplications`

* **타입**:

```
  {  
    key: string;  
    title: string;  
    type: 'discount_code' | '';  
  }[]
  ```

* **설명**: 적용된 할인 코드와 자동 할인의 배열

* **사용법**: 활성화된 모든 할인을 제목과 유형과 함께 표시해요

* **구조**: 각 할인에는 고유 키, 표시 제목, 유형 식별자가 포함돼요

`cartTotalDiscount`

* **타입**: `number`

* **설명**: 총 할인 금액(센트)

* **사용법**: 계산이나 커스텀 형식화를 위해 원시 할인 값에 접근해요

`showCartTotalDiscount`

* **타입**: `boolean`

* **설명**: 총 할인을 표시해야 하는지를 나타내요. `showTotalSavings`를 위해 지원 중단으로 표시되었지만, 아래 참고를 확인하세요 — 커스텀 템플릿 내부에서는 여전히 이 prop을 사용해야 해요.

* **사용법**: 설정에 따라 할인 정보를 조건부로 렌더링해요

`formattedCartTotalDiscount`

* **타입**: `string`

* **설명**: 미리 형식화된 총 할인 금액의 HTML 문자열. `formattedTotalSavings`를 위해 지원 중단으로 표시되었지만, 아래 참고를 확인하세요.

* **사용법**: 통화 기호와 함께 올바르게 형식화된 할인 금액을 표시해요

<Warning>
  **`showTotalSavings`와 `formattedTotalSavings`는 커스텀 템플릿 내부에서 사용할 수 없어요.** 이 값들은 모듈의 내부 컨텍스트에 존재하지만, Cart summary 템플릿에는 `showCartTotalDiscount`와 `formattedCartTotalDiscount`만 전달돼요 — 새로운 두 값을 읽으면 `undefined`가 반환돼요. 위의 두 prop을 사용하시고, 이 값들은 할인 총액만 표시하며 **Show compare-at price savings in footer total** 설정을 따르지 않는다는 점에 유의하세요.
</Warning>

`isRemovingDiscount`

* **타입**: `boolean`

* **설명**: 할인 제거 작업이 진행 중인지 나타내요

* **사용법**: 할인 제거 중 로딩 상태를 표시해요

`handleRemoveDiscount`

* **타입**: `() => Promise<void>`

* **설명**: 할인 코드 제거를 처리하는 함수

* **사용법**: 카트에서 적용된 할인 코드를 제거해요

`totalCompareAtPrice`

* **타입**: `number`

* **설명**: 비교 가격의 합계(카트의 모든 상품)

* **사용법**: 절약 금액이나 원래 가격 정보를 계산하고 표시해요

`totalAfterAllDiscounts`

* **타입**: `number`

* **설명**: 모든 할인 적용 후 최종 카트 총액(센트)

* **사용법**: 고객이 지불할 최종 가격을 표시해요

`originalTotalPrice`

* **타입**: `number`

* **설명**: 할인 전 원래 카트 총액(센트)

* **사용법**: 투명성과 절약 금액 계산을 위해 원래 가격을 표시해요

`cartItemCount`

* **타입**: `number`

* **설명**: 카트에 담긴 총 상품 수

* **사용법**: 카트 요약에 상품 수 정보를 표시해요

Trust Badges 모듈을 사용하면 조건부 배지 표시와 올바른 이미지 처리 같은 필수 신뢰 구축 기능을 유지하면서 신뢰 배지 표시를 원하는 디자인으로 커스터마이징할 수 있어요.

<div id="available-props-full-template-9">
  ### **사용 가능한 Props - Full template**
</div>

`showBadge`

* **타입**: `boolean`

* **설명**: 신뢰 배지를 표시해야 하는지를 나타내요

* **사용법**: 모듈 설정에 따라 신뢰 배지의 표시 여부를 제어해요

`badgeUrl`

* **타입**: `string`

* **설명**: 표시할 신뢰 배지 이미지의 URL

* **사용법**: 커스텀 구현에서 신뢰 배지 이미지의 소스 URL로 사용해요

Shopping Cart ({props.cartQuantity})

{rule.title}

Available Rewards...

{props.productTitle}