npm package: @kinxcdn/commerce-player
Description: React 기반 미디버스 커머스 플레이어 컴포넌트입니다.
Author: Soyeong Choi
Latest version: 1.6.5

# midibus commerce 플레이어 컴포넌트

React 기반 미디버스 커머스 플레이어 컴포넌트입니다.

## Installation

```shell
npm i @kinxcdn/commerce-player

# 또는

yarn add @kinxcdn/commerce-player
```
## Usage

### WidgetPlayer

#### Props

| Prop            | 타입       | 기본값                  | 설명                              |
|-----------------|----------|----------------------|---------------------------------|
| `collectionId`  | `string` | —                    | 불러올 미디어 컬렉션의 고유 ID              |
| `isPreview`     | `string` | `false`              | 프리뷰 모드 렌더링 여부 (`true`/`false`)  |
| `iconForm`      | `string` | `INSTA` \| `YOUTUBE` | 아이콘 형태                          |
| `iconShape`     | `string` | `MANY` \| `ONE`      | 아이콘 레이아웃                        |
| `iconSize`      | `string` | `120`                | 아이콘 크기(px)                      |
| `borderLine`    | `string` | `ALWAYS`             | 아이콘 테두리 유무                      |
| `exposeTitle`   | `string` | `true`               | 컬렉션 제목 노출 여부 (`true`/`false`)   |
| `player`        | `string` | `POPUP` \| `INLINE`  | 위젯 플레이어 유형                      |
| `rounded`       | `string` | `true`               | 아이콘 모서리 둥글기 여부 (`true`/`false`) |
| `titlePosition` | `string` | `BOTTOM` \| `TOP`    | 제목 위치 (`BOTTOM`/`TOP`)          |
| `hoverPlay` | `boolean` | `false`| 유튜브형 재생 아이콘 사용 시 마우스 오버 재생 기능 활성화 여부 |


---

#### 사용 예시

- React

```tsx
import WidgetPlayer from '@kinxcdn/commerce-player';

<WidgetPlayer
  collectionId="abc123"
  iconForm="YOUTUBE"
  iconShape="MANY"
  iconSize={80}
  borderLine="ALWAYS"
  exposeTitle={true}
  player="POPUP"
  rounded={false}
  titlePosition="inner"
/>
```


### LiveWidget

#### Props

| Prop                  | 타입                                   | 기본값 | 설명 |
|-----------------------|--------------------------------------|------|-----|
| `userId`              | `string`                             | —    | 라이브 목록을 불러올 미디버스 사용자 ID |
| `liveType`            | `"upcoming"` \| `"past"`           | —    | 예정 라이브/지난 라이브 구분 값 |
| `widgetType`          | `"ONE"` \| `"MULTIPLE"`           | —    | 카드 표시 형태 (단일/여러개) |
| `videoAlign`          | `"left"` \| `"right"` \| `"only"` | —    | 썸네일/버튼 정렬 및 표시 방식 |
| `aspectRatio`         | `"9/16"` \| `"1/1"`               | —    | 썸네일 비율 |
| `playback`            | `"autoplay"` \| `"hover"`         | —    | 재생 동작 모드 |
| `title`               | `string`                             | —    | 리스트 타이틀 문구 |
| `titleFontSize`       | `number`                             | —    | 타이틀 폰트 크기(px) |
| `isPreview`           | `boolean`                            | `false` | 프리뷰 모드 렌더링 여부 |
| `includeRepresentative` | `boolean`                          | —    | 대표 라이브 포함 여부 |
| `theme`               | `{ backgroundColor?, textColor? }`   | —    | 컴포넌트 색상 테마 |
| `layout`              | `{ paddingTop?, paddingBottom?, paddingLeft?, paddingRight? }` | — | 바깥 패딩 설정 |
| `card`                | `{ layout?, visibleCount?, gap?, sliderPerView?, gridColumns?, width?, borderRadius? }` | — | 카드/슬라이더 레이아웃 설정 |
| `sorting` (past 전용) | `"latest"` \| `"views"` \| `"likes"` | — | 지난 라이브 정렬 기준 |

---

#### 사용 예시

- React

```tsx
import { LiveWidget } from '@kinxcdn/commerce-player';

<LiveWidget
  userId="3"
  liveType="upcoming"
  widgetType="MULTIPLE"
  title="예정된 라이브"
  aspectRatio="1/1"
  includeRepresentative={true}
  theme={{ backgroundColor: '#fff', textColor: '#111' }}
  layout={{ paddingTop: 16, paddingBottom: 16 }}
  card={{ layout: 'scroll', visibleCount: 8, gridColumns: 2, gap: 12, borderRadius: 12 }}
/>
```

- JS (Web Component)

```html
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=no, maximum-scale=1.0, minimum-scale=1.0" />
    <meta http-equiv="X-UA-Compatible" content="ie=edge" />
    <title>LiveWidget 예제</title>
    <!-- CDN에서 commerce-player 로더 불러오기 -->
    <script src="https://unpkg.com/@kinxcdn/commerce-player/dist/commerce-player.min.js"></script>
  </head>
  <body>
    <div style="height: 600px; width: 100%">
      <mc-live-widget
        userId="3"
        liveType="upcoming"
        widgetType="MULTIPLE"
        title="예정된 라이브"
        aspectRatio="1/1"
        includeRepresentative="true"
        theme='{"backgroundColor":"#fff","textColor":"#111"}'
        layout='{"paddingTop":16,"paddingBottom":16}'
        card='{"layout":"scroll","visibleCount":8,"gridColumns":2,"gap":12,"borderRadius":12}'
      ></mc-live-widget>
    </div>
  </body>
  </html>
```

- JS

```html
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta
      name="viewport"
      content="width=device-width, initial-scale=1.0, user-scalable=no, maximum-scale=1.0, minimum-scale=1.0"
    />
    <meta http-equiv="X-UA-Compatible" content="ie=edge" />
    <title>WidgetPlayer 예제</title>
    <!-- CDN에서 commerce-player 로더 불러오기 -->
    <script src="https://unpkg.com/@kinxcdn/commerce-player/dist/commerce-player.min.js"></script>
  </head>
  <body>
    <div style="height: 600px; width: 100%;">
      <!-- 최소 설정: collectionId만 -->
      <mc-widget-player
        collectionId="6j7d3T4OG"
      ></mc-widget-player>

      <!-- 모든 옵션 설정 예시 -->
      <mc-widget-player
        collectionId="6j7d3T4OG"
        isPreview="true"
        iconForm="YOUTUBE"
        iconShape="ONE"
        iconSize="80"
        borderLine="NIGHT"
        exposeTitle="false"
        player="INLINE"
        rounded="false"
        titlePosition="TOP"
      ></mc-widget-player>
    </div>
  </body>
</html>

```