@uniai-fe/uds-templates 0.6.26 → 0.6.28

package/src/cctv/types/hook.ts

@@ -20,6 +20,24 @@ export type CctvRtcReconnectTrigger = (
   options?: RefetchOptions,
 ) => Promise<QueryObserverResult<API_Res_CctvRtcToken>>;
 
+/**
+ * CCTV; RTC stream scheduler 상태
+ */
+export type CctvRtcStreamScheduleStatus = "idle" | "queued" | "granted";
+
+/**
+ * CCTV; RTC stream 표시 단계
+ */
+export type CctvRtcStreamStage =
+  | "idle"
+  | "queued"
+  | "token-loading"
+  | "connecting"
+  | "live"
+  | "recovering"
+  | "error"
+  | "skipped-offline";
+
 /**
  * CCTV; useCctvRtcStream params
  * @property {CctvCompanyCameraData} [cam] 스트리밍 카메라 정보
@@ -64,6 +82,7 @@ export interface UseCctvRtcStreamError {
  * @property {boolean} isTokenLoading UI 표시 기준 토큰 발급 요청 진행 여부
  * @property {boolean} isTokenError 토큰 발급 실패 여부
  * @property {string | null} streamError 스트림 오류 메시지
+ * @property {CctvRtcStreamStage} streamStage stream 표시 단계
  */
 export interface UseCctvRtcStreamState extends UseCctvRtcStreamError {
   /**
@@ -88,6 +107,10 @@ export interface UseCctvRtcStreamState extends UseCctvRtcStreamError {
    * 재발급 중에는 기존 화면과 live count를 유지하기 위해 false로 smoothing될 수 있다.
    */
   isTokenLoading: boolean;
+  /**
+   * stream 표시 단계
+   */
+  streamStage: CctvRtcStreamStage;
 }
 
 /**
@@ -98,6 +121,7 @@ export interface UseCctvRtcStreamState extends UseCctvRtcStreamError {
  * @property {boolean} isStreaming UI 표시 기준 startWhepStream 진행 여부
  * @property {boolean} isTokenLoading UI 표시 기준 토큰 발급 요청 진행 여부
  * @property {boolean} isTokenError 토큰 발급 실패 여부
+ * @property {CctvRtcStreamStage} streamStage stream 표시 단계
  * @property {boolean} canReconnect UDS 내부 허용 사유와 grace/stagger를 통과해 재연결 호출이 가능한지 여부
  * @property {() => Promise<void>} refetchToken 토큰 재발급 함수
  * @property {() => Promise<QueryObserverResult<API_Res_CctvRtcToken>>} reconnectStream 재연결 trigger 함수

package/src/cctv/types/props.ts

@@ -1,5 +1,5 @@
 import type { CctvCompanyCameraData, CctvCompanyCameraList } from "./list";
-import type { CctvRtcReconnectTrigger } from "./hook";
+import type { CctvRtcReconnectTrigger, CctvRtcStreamStage } from "./hook";
 
 /**
  * CCTV; custom overlay render context
@@ -9,6 +9,7 @@ import type { CctvRtcReconnectTrigger } from "./hook";
  * @property {boolean | undefined} [isError] 영상 에러 상태 여부
  * @property {boolean | undefined} [isLive] 영상 live 상태 여부
  * @property {React.ReactNode} [overlayMessage] 기본 안내/에러 메시지 콘텐츠
+ * @property {CctvRtcStreamStage | undefined} [streamStage] stream 표시 단계
  * @property {boolean | undefined} [canReconnect] UDS 내부 허용 사유와 grace/stagger를 통과해 재연결 호출이 가능한지 여부
  * @property {CctvRtcReconnectTrigger | undefined} [reconnectStream] 재연결 trigger 함수
  */
@@ -37,6 +38,10 @@ export interface CctvVideoRenderOverlayContext {
    * 기본 안내/에러 메시지 콘텐츠
    */
   overlayMessage?: React.ReactNode;
+  /**
+   * stream 표시 단계
+   */
+  streamStage?: CctvRtcStreamStage;
   /**
    * UDS 내부 허용 사유와 grace/stagger를 통과해 재연결 호출이 가능한지 여부
    * @desc
@@ -130,6 +135,7 @@ export interface CctvVideoOverlayFooterProps {
  * @property {boolean} [isError] 에러 상태 여부
  * @property {boolean} [isLive] 영상이 정상적으로 재생 중인지 여부
  * @property {React.ReactNode} [overlayMessage] 에러/안내 메시지 콘텐츠
+ * @property {CctvRtcStreamStage} [streamStage] stream 표시 단계
  * @property {boolean} [canReconnect] UDS 내부 허용 사유와 grace/stagger를 통과해 재연결 호출이 가능한지 여부
  * @property {CctvRtcReconnectTrigger} [reconnectStream] 재연결 trigger 함수
  */
@@ -146,6 +152,10 @@ export interface CctvVideoStateProps {
    * 오버레이 메시지 콘텐츠
    */
   overlayMessage?: React.ReactNode;
+  /**
+   * stream 표시 단계
+   */
+  streamStage?: CctvRtcStreamStage;
   /**
    * UDS 내부 허용 사유와 grace/stagger를 통과해 재연결 호출이 가능한지 여부
    */
@@ -164,6 +174,7 @@ export interface CctvVideoStateProps {
  * @property {boolean} [isError] 에러 상태 여부
  * @property {boolean} [isLive] 영상이 정상적으로 재생 중인지 여부
  * @property {React.ReactNode} [overlayMessage] 에러/안내 메시지 콘텐츠
+ * @property {CctvRtcStreamStage} [streamStage] stream 표시 단계
  * @property {CctvVideoRenderOverlay} [renderOverlay] custom overlay 렌더 함수
  */
 export interface CctvVideoTemplateProps extends CctvVideoStateProps {

package/src/cctv/types/video-state.ts

@@ -1,5 +1,9 @@
 import type { CctvCompanyCameraData } from "./list";
-import type { UseCctvRtcStreamError, UseCctvRtcStreamState } from "./hook";
+import type {
+  CctvRtcStreamStage,
+  UseCctvRtcStreamError,
+  UseCctvRtcStreamState,
+} from "./hook";
 
 /**
  * CCTV; getOverlayMessage() params
@@ -11,10 +15,14 @@ import type { UseCctvRtcStreamError, UseCctvRtcStreamState } from "./hook";
  * @property {boolean} isTokenLoading UI 표시 기준 토큰 발급 요청 진행 여부
  * @property {boolean} isTokenError 토큰 발급 실패 여부
  * @property {string | null} streamError 스트림 오류 메시지
+ * @property {CctvRtcStreamStage} [streamStage] stream 표시 단계
  * @property {boolean} [canReconnect] UDS 내부 허용 사유와 grace/stagger를 통과해 재연결 호출이 가능한지 여부.
  * 오류 스타일 판정에는 직접 사용하지 않는다.
  */
-export interface CctvVideoOverlayMessageParams extends UseCctvRtcStreamState {
+export interface CctvVideoOverlayMessageParams extends Omit<
+  UseCctvRtcStreamState,
+  "streamStage"
+> {
   /**
    * 카메라 데이터
    */
@@ -27,6 +35,10 @@ export interface CctvVideoOverlayMessageParams extends UseCctvRtcStreamState {
    * 서버에서 cam 리스트를 가져오는 중인지 여부
    */
   isFetching?: boolean;
+  /**
+   * stream 표시 단계
+   */
+  streamStage?: CctvRtcStreamStage;
   /**
    * UDS 내부 허용 사유와 grace/stagger를 통과해 재연결 호출이 가능한지 여부
    * @desc
@@ -44,7 +56,10 @@ export interface CctvVideoOverlayMessageParams extends UseCctvRtcStreamState {
  * @property {boolean} isTokenError 토큰 발급 실패 여부
  * @property {string | null} streamError 스트림 오류 메시지
  */
-export interface CctvVideoLiveParams extends UseCctvRtcStreamState {
+export interface CctvVideoLiveParams extends Omit<
+  UseCctvRtcStreamState,
+  "streamStage"
+> {
   /**
    * 카메라 데이터
    */

package/src/cctv/utils/video-state.ts

@@ -7,6 +7,7 @@ import type {
 export const CCTV_MESSAGE = {
   selectCam: "카메라를 선택하세요.",
   fetching: "CCTV 데이터를 불러오는 중입니다.",
+  queued: "CCTV 연결 순서를 기다리고 있습니다.",
   preparing: "CCTV 영상을 연결하고 있습니다.",
   sessionEnded:
     "장시간 미사용으로 연결이 종료되었습니다. 계속 확인하시려면 다시 연결해 주세요.",
@@ -47,6 +48,7 @@ export function getOverlayMessage({
   isTokenLoading,
   isTokenError,
   isStreaming,
+  streamStage,
   streamError,
 }: CctvVideoOverlayMessageParams): string | null {
   if (!cam) {
@@ -62,6 +64,7 @@ export function getOverlayMessage({
   if (canReconnect && RTC_SESSION_ENDED_RECONNECT_STATES.has(connectionState)) {
     return CCTV_MESSAGE.sessionEnded;
   }
+  if (streamStage === "queued") return CCTV_MESSAGE.queued;
   // raw disconnected는 useCctvRtcStream에서 post-connected connected로 smoothing한다.
   if (isTokenLoading || isStreaming) return CCTV_MESSAGE.preparing;
   if (RTC_PREPARING_STATES.has(connectionState)) return CCTV_MESSAGE.preparing;