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

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

@@ -0,0 +1,35 @@
+import { default as React } from 'react';
+type GridProps = {
+    className?: string;
+    children?: React.ReactNode;
+} & React.JSX.IntrinsicElements["div"];
+type SlotProps = {
+    className?: string;
+    children?: React.ReactNode;
+} & React.JSX.IntrinsicElements["div"];
+export type VideoOverlayRenderProps = {
+    showControls: boolean;
+    onMouseMove: () => void;
+    onMouseLeave: () => void;
+    onClick: (event: React.MouseEvent<Element>) => void;
+    isFullscreen: boolean;
+    isPictureInPicture: boolean;
+};
+export type VideoOverlayProps = {
+    className?: string;
+    onOverlayClick?: () => void;
+    children: (props: VideoOverlayRenderProps) => React.ReactNode;
+};
+declare const VideoOverlay: ((props: VideoOverlayProps) => import("react/jsx-runtime").JSX.Element) & {
+    Grid: (props: GridProps) => import("react/jsx-runtime").JSX.Element;
+    TopLeft: (props: SlotProps) => import("react/jsx-runtime").JSX.Element;
+    TopCenter: (props: SlotProps) => import("react/jsx-runtime").JSX.Element;
+    TopRight: (props: SlotProps) => import("react/jsx-runtime").JSX.Element;
+    MiddleLeft: (props: SlotProps) => import("react/jsx-runtime").JSX.Element;
+    MiddleCenter: (props: SlotProps) => import("react/jsx-runtime").JSX.Element;
+    MiddleRight: (props: SlotProps) => import("react/jsx-runtime").JSX.Element;
+    BottomLeft: (props: SlotProps) => import("react/jsx-runtime").JSX.Element;
+    BottomCenter: (props: SlotProps) => import("react/jsx-runtime").JSX.Element;
+    BottomRight: (props: SlotProps) => import("react/jsx-runtime").JSX.Element;
+};
+export default VideoOverlay;

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

@@ -0,0 +1,2 @@
+export { default } from './VideoOverlay';
+export type { VideoOverlayRenderProps } from './VideoOverlay';

package/dist/components/VideoPlayer/components/Widgets/Button/Button.d.ts

@@ -0,0 +1,13 @@
+import { default as React } from 'react';
+import { Icon } from '../../../../Icon/Icon';
+export type ButtonProps = {
+    /** Icon 컴포넌트에 전달할 props (name 필수, size·color 등 선택). children이 있으면 무시됨. */
+    icon?: React.ComponentProps<typeof Icon>;
+    /** 아이콘 대신 렌더할 내용 (예: SpeedControl의 "1x" 텍스트) */
+    children?: React.ReactNode;
+    onClick?: () => void;
+    ariaLabel?: string;
+    className?: string;
+} & Omit<React.JSX.IntrinsicElements["button"], "onClick">;
+declare const Button: (props: ButtonProps) => import("react/jsx-runtime").JSX.Element;
+export default Button;

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

@@ -0,0 +1,2 @@
+export { default } from './Button';
+export type { ButtonProps } from './Button';

package/dist/components/VideoPlayer/components/Widgets/ProgressBar/ProgressBar.d.ts

@@ -0,0 +1,18 @@
+import { default as React } from 'react';
+type ProgressBarAsProps = {
+    defaultClassName: string;
+    progress: number;
+    buffered: number;
+    ariaLabel: string;
+    onPointerDown: (event: React.PointerEvent<HTMLDivElement>) => void;
+    onKeyDown: (event: React.KeyboardEvent<HTMLDivElement>) => void;
+    trackRef: React.RefObject<HTMLDivElement | null>;
+};
+export type ProgressBarProps = {
+    className?: string;
+    onInteractionChange?: (isActive: boolean) => void;
+    ariaLabel?: string;
+    as?: (props: ProgressBarAsProps) => React.ReactNode;
+};
+declare const ProgressBar: (props: ProgressBarProps) => import("react/jsx-runtime").JSX.Element;
+export default ProgressBar;

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

@@ -0,0 +1,2 @@
+export { default } from './ProgressBar';
+export type { ProgressBarProps } from './ProgressBar';

package/dist/components/VideoPlayer/components/Widgets/SpeedControl/SpeedControl.d.ts

@@ -0,0 +1,21 @@
+import { default as React } from 'react';
+type SpeedControlAsProps = {
+    defaultClassName: string;
+    playbackRate: number;
+    speedOptions: readonly number[];
+    variant: "menu" | "cycle";
+    isOpen: boolean;
+    ariaLabel: string;
+    onButtonClick: () => void;
+    onSpeedSelect: (speed: number) => void;
+    onMouseEnter: () => void;
+    onMouseLeave: () => void;
+};
+type SpeedControlProps = {
+    className?: string;
+    variant?: "menu" | "cycle";
+    ariaLabel?: string;
+    as?: (props: SpeedControlAsProps) => React.ReactNode;
+};
+declare const SpeedControl: (props: SpeedControlProps) => import("react/jsx-runtime").JSX.Element;
+export default SpeedControl;

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

@@ -0,0 +1 @@
+export { default } from './SpeedControl';

package/dist/components/VideoPlayer/components/Widgets/Time/Time.d.ts

@@ -0,0 +1,15 @@
+import { default as React } from 'react';
+type TimeAsProps = {
+    defaultClassName: string;
+    currentTime: number;
+    duration: number;
+    formattedCurrentTime: string;
+    formattedDuration: string;
+};
+export type TimeProps = {
+    className?: string;
+    formatTime?: (time: number) => string;
+    as?: (props: TimeAsProps) => React.ReactNode;
+};
+declare const Time: (props: TimeProps) => import("react/jsx-runtime").JSX.Element;
+export default Time;

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

@@ -0,0 +1,2 @@
+export { default } from './Time';
+export type { TimeProps } from './Time';

package/dist/components/VideoPlayer/components/Widgets/VolumeControl/VolumeControl.d.ts

@@ -0,0 +1,34 @@
+import { default as React } from 'react';
+import { IconName, StrictIconProps } from '../../../../Icon/Icon';
+/** 아이콘: 이름만 주거나, name + 기타 Icon props 객체 */
+type VolumeIconProp = IconName | (Pick<StrictIconProps, "name"> & Partial<Omit<StrictIconProps, "name">>);
+type VolumeControlAsProps = {
+    defaultClassName: string;
+    volume: number;
+    isMuted: boolean;
+    ariaLabel: string;
+    onMuteToggle: () => void;
+    onVolumeChange: (volume: number) => void;
+    volumeOnIcon: IconName;
+    volumeOffIcon: IconName;
+    sliderVisible: boolean;
+    sliderValue: number;
+    onSliderFocus: (focused: boolean) => void;
+    onPointerDown: (event: React.PointerEvent<Element>) => void;
+    trackRef: React.RefObject<HTMLDivElement | null>;
+};
+export type VolumeControlProps = {
+    className?: string;
+    onInteractionChange?: (isActive: boolean) => void;
+    icons?: {
+        volumeOn?: VolumeIconProp;
+        volumeOff?: VolumeIconProp;
+    };
+    aria?: {
+        mute?: string;
+        unmute?: string;
+    };
+    as?: (props: VolumeControlAsProps) => React.ReactNode;
+};
+declare const VolumeControl: (props: VolumeControlProps) => import("react/jsx-runtime").JSX.Element;
+export default VolumeControl;

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

@@ -0,0 +1,2 @@
+export { default } from './VolumeControl';
+export type { VolumeControlProps } from './VolumeControl';

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

@@ -0,0 +1,29 @@
+export declare const Widgets: {
+    Button: (props: import('./Button').ButtonProps) => import("react/jsx-runtime").JSX.Element;
+    ProgressBar: (props: import('./ProgressBar').ProgressBarProps) => import("react/jsx-runtime").JSX.Element;
+    VolumeControl: (props: import('./VolumeControl').VolumeControlProps) => import("react/jsx-runtime").JSX.Element;
+    SpeedControl: (props: {
+        className?: string;
+        variant?: "menu" | "cycle";
+        ariaLabel?: string;
+        as?: (props: {
+            defaultClassName: string;
+            playbackRate: number;
+            speedOptions: readonly number[];
+            variant: "menu" | "cycle";
+            isOpen: boolean;
+            ariaLabel: string;
+            onButtonClick: () => void;
+            onSpeedSelect: (speed: number) => void;
+            onMouseEnter: () => void;
+            onMouseLeave: () => void;
+        }) => React.ReactNode;
+    }) => import("react/jsx-runtime").JSX.Element;
+    Time: (props: import('./Time').TimeProps) => import("react/jsx-runtime").JSX.Element;
+};
+export { default as Button } from './Button';
+export type { ButtonProps } from './Button';
+export { default as ProgressBar } from './ProgressBar';
+export { default as VolumeControl } from './VolumeControl';
+export { default as SpeedControl } from './SpeedControl';
+export { default as Time } from './Time';

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

@@ -0,0 +1,10 @@
+export { default as VideoOverlay } from './VideoOverlay';
+export { default as Loading } from './Loading';
+export { default as Error } from './Error';
+export { default as Frame } from './Frame';
+export { default as Player } from './Player';
+export { default as Thumbnail } from './Thumbnail';
+export { Widgets } from './Widgets';
+export type { ButtonProps } from './Widgets';
+export type { PlayerProps } from './Player';
+export type { ThumbnailProps } from './Thumbnail';

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

@@ -0,0 +1,4 @@
+export { useVideoPlayerStore, useVideoPlayerShallow, VideoPlayerStoreContext, VideoPlayerImageContext, useVideoPlayerImage, DefaultImage, type VideoPlayerStoreApi, } from './videoPlayer.context';
+export { default as VideoPlayerProvider } from './videoPlayer.provider';
+export { createVideoPlayerStore, resolveVideoPlayerStoreConfig, } from './videoPlayer.store';
+export type { VideoJsPlayer, VideoPlayerStoreConfig, VideoPlayerTextTrack, VideoPlayerEvents, VideoPlayerState, VideoPlayerActions, VideoPlayerStore, VideoPlayerExternalController, VideoPlayerImageProps, VideoPlayerImageComponent, VideoPlayerProviderProps, } from './videoPlayer.types';

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

@@ -0,0 +1,15 @@
+import { default as React } from 'react';
+import { createVideoPlayerStore } from './videoPlayer.store';
+import { VideoPlayerStore, VideoPlayerImageProps, VideoPlayerImageComponent } from './videoPlayer.types';
+/**
+ * VideoPlayer 스토어 API 타입 (createVideoPlayerStore의 반환 타입)
+ */
+export type VideoPlayerStoreApi = ReturnType<typeof createVideoPlayerStore>;
+export type { VideoPlayerImageProps, VideoPlayerImageComponent };
+export declare const VideoPlayerStoreContext: React.Context<import('zustand').UseBoundStore<import('zustand').StoreApi<VideoPlayerStore>> | undefined>;
+export declare const DefaultImage: (props: VideoPlayerImageProps) => import("react/jsx-runtime").JSX.Element;
+export declare const VideoPlayerImageContext: React.Context<VideoPlayerImageComponent>;
+export declare const useVideoPlayerImage: () => VideoPlayerImageComponent;
+export declare const useVideoPlayerStore: <R>(selector: (store: VideoPlayerStore) => R) => R;
+export declare function useVideoPlayerShallow<R>(selector: (store: VideoPlayerStore) => R): R;
+export declare function useVideoPlayerShallow<K extends keyof VideoPlayerStore>(keys: readonly K[]): Pick<VideoPlayerStore, K>;

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

@@ -0,0 +1,3 @@
+import { VideoPlayerProviderProps } from './videoPlayer.types';
+declare const VideoPlayerProvider: (props: VideoPlayerProviderProps) => import("react/jsx-runtime").JSX.Element;
+export default VideoPlayerProvider;

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

@@ -0,0 +1,27 @@
+import { VideoPlayerStore, VideoPlayerStoreConfig, VideoPlayerEvents, VideoPlayerTextTrack } from './videoPlayer.types';
+import { default as videojs } from 'video.js';
+export declare const resolveVideoPlayerStoreConfig: (config?: Partial<VideoPlayerStoreConfig>) => VideoPlayerStoreConfig;
+export declare const createVideoPlayerStore: (config?: Partial<VideoPlayerStoreConfig>, videoProps?: {
+    width?: string | number;
+    height?: string | number;
+    src?: string;
+    sources?: {
+        src: string;
+        type: string;
+    }[];
+    speedOptions?: number[];
+    playerOptions?: Parameters<typeof videojs>[1];
+    events?: VideoPlayerEvents;
+    disableVideoJsStyles?: boolean;
+    tracks?: VideoPlayerTextTrack[];
+    initialActiveCaptionLang?: string | null;
+    activeCaptionLang?: string | null;
+    onCaptionLangChange?: (lang: string | null) => void;
+    autoHide?: boolean;
+    autoHideDelayMs?: number;
+    overlayClickAction?: "toggle-play" | "none";
+    loadingText?: string;
+    errorTitle?: string;
+    errorDescription?: string;
+    errorRetry?: string;
+}) => import('zustand').UseBoundStore<import('zustand').StoreApi<VideoPlayerStore>>;

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

@@ -0,0 +1,18 @@
+export { default as VideoPlayer } from './VideoPlayer';
+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;