@weing-dev/ui-kit-primitive 0.2.0 → 0.3.0

package/dist/components/VideoPlayer/context/videoPlayer.types.d.ts

@@ -0,0 +1,351 @@
+import { default as React } from 'react';
+import { default as videojs } from 'video.js';
+/**
+ * Video.js 플레이어 인스턴스 타입
+ */
+export type VideoJsPlayer = ReturnType<typeof videojs>;
+/**
+ * VideoPlayer 스토어 설정 타입
+ */
+export type VideoPlayerStoreConfig = {
+    /** 볼륨 값을 `localStorage` 등에 저장할지 여부 */
+    volumePersist: boolean;
+    /** 볼륨 영속화 시 사용하는 스토리지 키 */
+    volumeStorageKey: string;
+    /** 저장값이 없을 때 사용할 기본 볼륨(0~1) */
+    volumeFallback: number;
+    /** 최초(및 리셋 시) 재생 속도 배율 */
+    playbackRateDefault: number;
+};
+/**
+ * 자막 트랙 한 개 (HTML track / Video.js text track).
+ * Video.js에 넘기는 트랙의 `default` 여부는 여기서 받지 않고 `Player`가 `activeCaptionLang`·`srclang`으로 계산한다.
+ */
+export type VideoPlayerTextTrack = {
+    /** 트랙 리소스 URL (VTT 등) */
+    src: string;
+    /** 트랙 종류. 미지정 시 플레이어/브라우저 기본에 따름 */
+    kind?: "subtitles" | "captions" | "descriptions" | "chapters" | "metadata";
+    /** BCP 47 언어 태그. 자막 on/off·선택에 사용 */
+    srclang?: string;
+    /** UI에 표시할 트랙 이름 */
+    label?: string;
+};
+/**
+ * VideoPlayer 이벤트 타입
+ */
+export type VideoPlayerEvents = {
+    /** Video.js 인스턴스가 준비되었을 때 */
+    onReady?: (player: VideoJsPlayer) => void;
+    /** 미디어 로드가 시작되었을 때 */
+    onLoadStart?: () => void;
+    /** 재생을 시작할 수 있을 만큼 버퍼가 찼을 때 */
+    onCanPlay?: () => void;
+    /** 재생이 시작되었을 때 */
+    onPlay?: () => void;
+    /** 일시정지되었을 때 */
+    onPause?: () => void;
+    /**
+     * 재생 위치가 갱신될 때
+     * @param currentTime 초 단위 현재 재생 시각
+     */
+    onTimeUpdate?: (currentTime: number) => void;
+    /**
+     * 버퍼 진행이 갱신될 때
+     * @param buffered 초 단위로 해석 가능한 버퍼 관련 값(구현에 따름)
+     */
+    onProgress?: (buffered: number) => void;
+    /**
+     * 볼륨이 변경되었을 때
+     * @param volume 0~1
+     */
+    onVolumeChange?: (volume: number) => void;
+    /**
+     * 재생 배속이 변경되었을 때
+     * @param rate 배율(예: 1, 1.5)
+     */
+    onRateChange?: (rate: number) => void;
+    /**
+     * 전체화면 상태가 바뀌었을 때
+     * @param isFullscreen 전체화면이면 true
+     */
+    onFullscreenChange?: (isFullscreen: boolean) => void;
+    /**
+     * Picture-in-Picture 상태가 바뀌었을 때
+     * @param active PiP 모드이면 true
+     */
+    onPictureInPictureChange?: (active: boolean) => void;
+    /**
+     * 총 재생 길이가 확정·변경되었을 때
+     * @param duration 초 단위 길이
+     */
+    onDurationChange?: (duration: number) => void;
+    /** 재생이 끝까지 도달했을 때(video `ended`). 스토어의 `isPlaying`은 false로 맞춤 */
+    onEnded?: () => void;
+    /**
+     * 재생 또는 로드 중 오류가 났을 때
+     * @param error 원인 객체(플랫폼·Video.js에 따라 상이)
+     */
+    onError?: (error: unknown) => void;
+};
+/**
+ * VideoPlayer 스토어 상태 타입
+ */
+export type VideoPlayerState = {
+    /** 미디어가 아직 재생 가능하지 않고 로딩 중인지 */
+    isLoading: boolean;
+    /** 재생/로드 오류가 발생한 상태인지 */
+    hasError: boolean;
+    /** 현재 재생 중인지 */
+    isPlaying: boolean;
+    /** 현재 재생 시각(초) */
+    currentTime: number;
+    /** 총 길이(초). 미확정 시 0에 가깝게 유지될 수 있음 */
+    duration: number;
+    /** 버퍼링 관련 진행 값(초 단위로 쓰는 흐름과 연동) */
+    buffered: number;
+    /** 볼륨 0~1 */
+    volume: number;
+    /** 현재 재생 배속 */
+    playbackRate: number;
+    /** 브라우저 전체화면 API 기준 전체화면 여부 */
+    isFullscreen: boolean;
+    /** Picture-in-Picture 모드 여부 */
+    isPictureInPicture: boolean;
+    /** 음소거 여부 */
+    isMuted: boolean;
+    /** 음소거 전 마지막 볼륨(토글 복원용) */
+    previousVolume: number;
+    /** Video.js 플레이어 인스턴스. 언마운트 전까지 null일 수 있음 */
+    player: VideoJsPlayer | null;
+    /** 플레이어 컨테이너 너비(CSS 값 또는 px 숫자) */
+    width: string | number;
+    /** 플레이어 컨테이너 높이(CSS 값 또는 px 숫자) */
+    height: string | number;
+    /** 단일 소스 URL. `sources`와 함께 쓰일 때 우선순위는 Player 구현에 따름 */
+    src: string | null;
+    /** 다중 소스(코덱/포맷별). null이면 미설정 */
+    sources: {
+        src: string;
+        type: string;
+    }[] | null;
+    /** 배속 선택 UI에 노출할 배율 목록 */
+    speedOptions: number[];
+    /** Video.js 생성자에 넘기는 옵션 */
+    playerOptions: Parameters<typeof videojs>[1] | null;
+    /** Root 등에서 주입한 이벤트 콜백 묶음 */
+    events: VideoPlayerEvents | null;
+    /** true면 Video.js 기본 스타일 주입을 생략 */
+    disableVideoJsStyles: boolean;
+    /** 로드할 텍스트 트랙(자막 등) 목록 */
+    tracks: VideoPlayerTextTrack[];
+    /**
+     * 현재 표시할 자막의 `srclang`. `null`이면 자막 끔.
+     * 외부에서 `activeCaptionLang`으로 제어하거나 스토어 내부에서 관리.
+     */
+    activeCaptionLang: string | null;
+    /**
+     * controlled 모드: 자막 언어가 바뀔 때 부모에 알림
+     * @param lang 선택된 `srclang`, 끔이면 null
+     */
+    onCaptionLangChange?: (lang: string | null) => void;
+    /** 오버레이 UI(그리드 영역)를 일정 시간 후 자동으로 숨길지 */
+    autoHide: boolean;
+    /** 자동 숨김까지 유휴 시간(ms) */
+    autoHideDelayMs: number;
+    /**
+     * 오버레이 빈 영역 클릭 시 동작.
+     * `toggle-play`: 재생/일시정지 토글, `none`: 토글 없음(전용 버튼만)
+     */
+    overlayClickAction: "toggle-play" | "none";
+    /** 오버레이 안의 컨트롤(슬롯 콘텐츠)가 보이는지 */
+    overlayControlsVisible: boolean;
+    /**
+     * true면 재생 중에도 자동 숨김 타이머를 돌리지 않음.
+     * 예: 설정 메뉴가 열린 동안 컨트롤을 유지할 때
+     */
+    overlayAutoHideSuspended: boolean;
+    /** 로딩 UI에 표시할 문구 */
+    loadingText: string;
+    /** 에러 UI 제목 */
+    errorTitle: string;
+    /** 에러 UI 본문 설명 */
+    errorDescription: string;
+    /** 에러 UI 재시도 버튼 라벨 */
+    errorRetry: string;
+};
+/**
+ * VideoPlayer 스토어 액션 타입
+ */
+export type VideoPlayerActions = {
+    /**
+     * 상태를 부분 갱신. 단순 필드 덮어쓰기용
+     * @param updates 바꿀 필드만 담은 객체
+     */
+    setState: (updates: Partial<VideoPlayerState>) => void;
+    /** 오버레이 위에서 포인터가 움직임 → 자동 숨김 타이머 리셋, 필요 시 컨트롤 표시 */
+    notifyOverlayPointerActivity: () => void;
+    /** 오버레이 루트에서 포인터가 이탈했을 때 호출 */
+    notifyOverlayPointerLeave: () => void;
+    /** 예약된 오버레이 자동 숨김 타이머만 취소(언마운트 등) */
+    clearOverlayAutoHideTimer: () => void;
+    /** Video.js 인스턴스를 스토어에 연결하거나 해제 */
+    setPlayer: (player: VideoJsPlayer | null) => void;
+    /**
+     * 볼륨만 갱신(내부에서 음소거·previousVolume 등과 동기화)
+     * @param volume 0~1
+     */
+    setVolume: (volume: number) => void;
+    /** 재생 ↔ 일시정지 토글 */
+    handlePlayPause: () => void;
+    /**
+     * 지정 시각으로 시킹
+     * @param time 초
+     */
+    handleSeek: (time: number) => void;
+    /**
+     * 지정 시각으로 시킹한 뒤 재생을 시도한다.
+     * @param time 초
+     */
+    handleSeekAndPlay: (time: number) => void;
+    /**
+     * 볼륨 변경(슬라이더 등 UI에서 호출)
+     * @param volume 0~1
+     */
+    handleVolumeChange: (volume: number) => void;
+    /**
+     * 재생 배속 변경
+     * @param speed 배율(`speedOptions`에 포함된 값 권장)
+     */
+    handleSpeedChange: (speed: number) => void;
+    /** 전체화면 입·퇴장 토글 */
+    handleFullscreenToggle: () => void;
+    /** Picture-in-Picture 입·퇴장 토글 */
+    handlePictureInPictureToggle: () => void;
+    /** 음소거 토글 */
+    handleMuteToggle: () => void;
+    /** 자막 표시 토글(언어는 `activeCaptionLang` 흐름과 연동) */
+    handleCaptionToggle: () => void;
+    /**
+     * 표시할 자막 언어 설정
+     * @param lang `srclang` 또는 `null`(끔)
+     */
+    setActiveCaptionLang: (lang: string | null) => void;
+};
+/**
+ * VideoPlayer 스토어 전체 타입 (State + Actions)
+ */
+export type VideoPlayerStore = VideoPlayerState & VideoPlayerActions;
+/**
+ * VideoPlayer 외부 제어 API 타입.
+ * `VideoPlayer.Root`의 `controllerRef`로 받아 컨텍스트 밖에서도 안전하게 제어할 수 있다.
+ */
+export type VideoPlayerExternalController = {
+    /** 현재 Video.js 플레이어 인스턴스 반환 (없으면 null) */
+    getPlayer: () => VideoJsPlayer | null;
+    /** 현재 재생 중 여부 */
+    isPlaying: () => boolean;
+    /** 현재 재생 시각(초) */
+    getCurrentTime: () => number;
+    /** 총 길이(초) */
+    getDuration: () => number;
+    /** 재생 */
+    play: () => void;
+    /** 일시정지 */
+    pause: () => void;
+    /** 재생/일시정지 토글 */
+    togglePlayPause: () => void;
+    /**
+     * 지정 시점으로 이동
+     * @param time - 초 단위 재생 위치
+     */
+    seek: (time: number) => void;
+    /**
+     * 지정 시점으로 이동 후 재생
+     * @param time - 초 단위 재생 위치
+     */
+    seekAndPlay: (time: number) => void;
+    /** Picture-in-Picture 토글 */
+    togglePictureInPicture: () => void;
+    /** 전체화면 토글 */
+    toggleFullscreen: () => void;
+};
+/**
+ * VideoPlayer 이미지 컴포넌트의 Props 타입
+ */
+export type VideoPlayerImageProps = {
+    /** 이미지 URL */
+    src: string;
+    /** 대체 텍스트(접근성) */
+    alt: string;
+    /** 픽셀 너비(선택) */
+    width?: number;
+    /** 픽셀 높이(선택) */
+    height?: number;
+    /** 추가 CSS 클래스 */
+    className?: string;
+};
+/**
+ * VideoPlayer 이미지 컴포넌트 타입
+ */
+export type VideoPlayerImageComponent = React.ComponentType<VideoPlayerImageProps>;
+/**
+ * VideoPlayer Provider Props 타입
+ */
+export type VideoPlayerProviderProps = {
+    /** Provider 하위 트리 */
+    children: React.ReactNode;
+    /** 스토어 기본 설정 일부만 덮어쓰기 */
+    storeConfig?: Partial<VideoPlayerStoreConfig>;
+    /** 플레이어 레이아웃 너비 */
+    width?: string | number;
+    /** 플레이어 레이아웃 높이 */
+    height?: string | number;
+    /** 단일 미디어 소스 URL */
+    src?: string;
+    /** 타입별 소스 배열(예: HLS + MP4) */
+    sources?: {
+        src: string;
+        type: string;
+    }[];
+    /** 배속 선택지 배열 */
+    speedOptions?: number[];
+    /** Video.js 옵션 */
+    playerOptions?: Parameters<typeof videojs>[1];
+    /** 재생·로드 라이프사이클 콜백 */
+    events?: VideoPlayerEvents;
+    /** Video.js 기본 스타일 비활성화 */
+    disableVideoJsStyles?: boolean;
+    /** 자막 등 텍스트 트랙 */
+    tracks?: VideoPlayerTextTrack[];
+    /** 마운트 시 초기 자막 언어(`srclang`). null이면 끔 */
+    initialActiveCaptionLang?: string | null;
+    /**
+     * controlled: 현재 자막 언어. 넣으면 스토어가 이 값을 따름
+     */
+    activeCaptionLang?: string | null;
+    /**
+     * controlled: 자막 언어 변경 시 부모 콜백
+     * @param lang 선택 언어 또는 null
+     */
+    onCaptionLangChange?: (lang: string | null) => void;
+    /** 오버레이 자동 숨김 사용 여부 */
+    autoHide?: boolean;
+    /** 자동 숨김 지연(ms) */
+    autoHideDelayMs?: number;
+    /** 오버레이 빈 영역 클릭 시 재생 토글 여부 */
+    overlayClickAction?: "toggle-play" | "none";
+    /** 로딩 오버레이 문구 */
+    loadingText?: string;
+    /** 에러 제목 */
+    errorTitle?: string;
+    /** 에러 설명 */
+    errorDescription?: string;
+    /** 에러 재시도 버튼 문구 */
+    errorRetry?: string;
+    /**
+     * 외부에서 재생·시킹·PiP 등을 제어할 때 사용.
+     * 마운트 후 `current`에 `VideoPlayerExternalController`가 채워지며, 언마운트 시 `null`로 비운다.
+     */
+    controllerRef?: React.MutableRefObject<VideoPlayerExternalController | null>;
+};

package/dist/components/VideoPlayer/index.d.ts

@@ -1,4 +1,18 @@
 export { default as VideoPlayer } from './VideoPlayer';
-export type { VideoPlayerProps, VideoPlayerRootProps, VideoPlayerControls, VideoPlayerTexts, VideoPlayerAria, VideoPlayerIcons, VideoPlayerEvents, } from './VideoPlayer';
-export { useVideoPlayerStore, useVideoPlayerShallow, VideoPlayerStoreContext, VideoPlayerImageContext, useVideoPlayerImage, DefaultImage, VideoPlayerProvider, createVideoPlayerStore, resolveVideoPlayerStoreConfig, type VideoPlayerStoreApi, type VideoPlayerImageComponent, type VideoPlayerImageProps, type VideoPlayerStore, type VideoPlayerState, type VideoPlayerActions, type VideoPlayerStoreConfig, } from './context';
+export type { VideoPlayerRootProps } from './VideoPlayer';
+export { useVideoPlayerStore, useVideoPlayerShallow, VideoPlayerStoreContext, VideoPlayerImageContext, useVideoPlayerImage, DefaultImage, VideoPlayerProvider, createVideoPlayerStore, resolveVideoPlayerStoreConfig, } from './context';
 export { VIDEO_PLAYER_DEFAULTS } from './videoPlayer.constants';
+export { convertSrtToVtt, getHtmlVideoElementFromVideoJs, isSrtSubtitleSource, parseWebVttToCues, } from './VideoPlayer.utils';
+export type { VttCue } from './VideoPlayer.utils';
+export { convertSrtToVtt as videeoPlayerConvertSrtToVtt, parseWebVttToCues as videeoPlayerParseWebVttToCues, convertSrtToVtt as VideeoPlayerConvertSrtToVtt, parseWebVttToCues as VideeoPlayerParseWebVttToCues, } from './VideoPlayer.utils';
+export type { VttCue as VideeoPlayerVttCue } from './VideoPlayer.utils';
+export type { VideoPlayerStoreApi, VideoPlayerImageComponent, VideoPlayerImageProps, VideoPlayerStore, VideoPlayerState, VideoPlayerActions, VideoPlayerStoreConfig, VideoPlayerTextTrack, VideoPlayerEvents, VideoPlayerExternalController, VideoJsPlayer, VideoPlayerProviderProps, } from './context';
+export type { IVideoPlayer, VideoPlayerRootProps as VideoPlayerProps, } from './VideoPlayer';
+export type VideoPlayerControls = Record<string, never>;
+export type VideoPlayerTexts = Record<string, never>;
+export type VideoPlayerAria = Record<string, never>;
+export type VideoPlayerIcons = Record<string, never>;
+export type VideeoPlayerControls = VideoPlayerControls;
+export type VideeoPlayerTexts = VideoPlayerTexts;
+export type VideeoPlayerAria = VideoPlayerAria;
+export type VideeoPlayerIcons = VideoPlayerIcons;

package/dist/components/VideoPlayer/videoPlayer.constants.d.ts

@@ -29,9 +29,13 @@ export declare const VIDEO_PLAYER_DEFAULTS: {
         readonly pause: "일시정지";
         readonly fullscreenEnter: "전체화면";
         readonly fullscreenExit: "전체화면 종료";
+        readonly pictureInPictureEnter: "Picture-in-Picture";
+        readonly pictureInPictureExit: "Picture-in-Picture 종료";
         readonly speed: "재생 속도 조절";
         readonly mute: "음소거";
         readonly unmute: "음소거 해제";
+        readonly captionOn: "자막 켜기";
+        readonly captionOff: "자막 끄기";
         readonly back: "뒤로가기";
         readonly share: "공유";
     };
@@ -42,7 +46,10 @@ export declare const VIDEO_PLAYER_DEFAULTS: {
         readonly share: "Share";
         readonly volumeOn: "VolumeUp";
         readonly volumeOff: "VolumeOff";
+        readonly caption: "SubtitleFilled";
         readonly fullscreenEnter: "FullScreen";
         readonly fullscreenExit: "FullScreenClose";
+        readonly pictureInPictureEnter: "Pip";
+        readonly pictureInPictureExit: "PipExit";
     };
 };

package/dist/entry/components.d.ts

@@ -85,5 +85,6 @@ export { default as TimeInput } from '../components/TimeInput/TimeInput';
 export { default as List } from '../components/List/List';
 /** Thumbnail */
 export { default as Thumbnail } from '../components/Thumbnail/Thumbnail';
-export { default as VideoPlayer } from '../components/VideoPlayer/VideoPlayer';
+/** VideoPlayer */
+export { VideoPlayer, VIDEO_PLAYER_DEFAULTS, convertSrtToVtt, getHtmlVideoElementFromVideoJs, isSrtSubtitleSource, parseWebVttToCues, videeoPlayerConvertSrtToVtt, videeoPlayerParseWebVttToCues, VideeoPlayerConvertSrtToVtt, VideeoPlayerParseWebVttToCues, } from '../components/VideoPlayer';
 export {};

package/dist/entry/types.d.ts

@@ -25,8 +25,8 @@ export type { ScrollCalendarContextType } from '../components/ScrollCalendar/Scr
 export type { CascaderOption } from '../components/Cascader/Cascader.context';
 /** WeeklyCalendar */
 export type { WeeklyCalendarContextType, EventItemAsProps, EventItemPopperAsProps, } from '../components/WeeklyCalendar/WeeklyCalendar.context';
-export type { VideoPlayerProps, VideoPlayerRootProps, VideoPlayerControls, VideoPlayerTexts, VideoPlayerAria, VideoPlayerIcons, VideoPlayerEvents, } from '../components/VideoPlayer/VideoPlayer';
-export type { VideoPlayerStoreApi, VideoPlayerImageComponent, VideoPlayerImageProps, VideoPlayerStore, VideoPlayerState, VideoPlayerActions, VideoPlayerStoreConfig, } from '../components/VideoPlayer/context';
+/** VideoPlayer */
+export type { IVideoPlayer, VideoPlayerProps, VideoPlayerRootProps, VideoPlayerControls, VideoPlayerTexts, VideoPlayerAria, VideoPlayerIcons, VideeoPlayerControls, VideeoPlayerTexts, VideeoPlayerAria, VideeoPlayerIcons, VideoPlayerEvents, VideoPlayerStoreApi, VideoPlayerImageComponent, VideoPlayerImageProps, VideoPlayerStore, VideoPlayerState, VideoPlayerActions, VideoPlayerStoreConfig, VideoPlayerExternalController, VideoJsPlayer, VideoPlayerProviderProps, VttCue, VideeoPlayerVttCue, } from '../components/VideoPlayer';
 /** Icon */
 export type { IconProviderProps, IconRegistry, } from '../components/Icon/context';
 /** Editor */