@uniai-fe/uds-templates 0.5.16 → 0.5.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniai-fe/uds-templates",
-  "version": "0.5.16",
+  "version": "0.5.17",
   "description": "UNIAI Design System; UI Templates Package",
   "type": "module",
   "private": false,

package/src/cctv/components/cam-list/Item.tsx

@@ -57,7 +57,13 @@ export default function CCTVCamListItem({
         footerOptions={{ activeTitle: true, activeOpenButton: true, cam }}
         // 변경 설명: list item custom overlay는 template seam 하나만 따라간다.
         renderOverlay={renderOverlay}
-        {...{ isError, overlayMessage, isLive }}
+        {...{
+          isError,
+          overlayMessage,
+          isLive,
+          canReconnect: rtcCtx.canReconnect,
+          reconnectStream: rtcCtx.reconnectStream,
+        }}
       />
     </li>
   );

package/src/cctv/components/pagination/list/Item.tsx

@@ -59,7 +59,13 @@ export default function CCTVPaginationListItem({
             title: cam.cam_name,
           }}
           footerOptions={{ cam }}
-          {...{ isError, overlayMessage, isLive }}
+          {...{
+            isError,
+            overlayMessage,
+            isLive,
+            canReconnect: rtcCtx.canReconnect,
+            reconnectStream: rtcCtx.reconnectStream,
+          }}
         />
       </button>
     </li>

package/src/cctv/components/video/Template.tsx

@@ -18,6 +18,8 @@ import type { CctvVideoTemplateProps } from "../../types/props";
  * @property {React.ReactNode} [overlayMessage]
  * @property {boolean} [isLive]
  * @property {CctvCompanyCameraData} [cam]
+ * @property {boolean} [canReconnect]
+ * @property {CctvRtcReconnectTrigger} [reconnectStream]
  * @property {CctvVideoRenderOverlay} [renderOverlay]
  * @property {React.Ref<HTMLVideoElement>} ref
  */
@@ -31,6 +33,8 @@ const CCTVVideoTemplate = forwardRef<HTMLVideoElement, CctvVideoTemplateProps>(
       isError,
       isLive,
       overlayMessage,
+      canReconnect,
+      reconnectStream,
       renderOverlay,
     },
     ref,
@@ -56,6 +60,8 @@ const CCTVVideoTemplate = forwardRef<HTMLVideoElement, CctvVideoTemplateProps>(
             isError,
             isLive,
             overlayMessage,
+            canReconnect,
+            reconnectStream,
           })
         : defaultOverlay;
 

package/src/cctv/components/viewer/desktop/Video.tsx

@@ -57,7 +57,13 @@ export default function CCTVViewerDesktopVideo({
       footerOptions={{ activeTitle: false }}
       // 변경 설명: viewer video는 service custom overlay를 직접 수용하는 첫 public entry다.
       renderOverlay={renderOverlay}
-      {...{ isError, overlayMessage, isLive }}
+      {...{
+        isError,
+        overlayMessage,
+        isLive,
+        canReconnect: rtcCtx.canReconnect,
+        reconnectStream: rtcCtx.reconnectStream,
+      }}
     />
   );
 }

package/src/cctv/hooks/useRtcStream.ts

@@ -10,11 +10,17 @@ import {
   useCctvApiUrl,
   useCctvRtcStreamRegistry,
 } from "../components/Provider";
-import type { UseCctvRtcStreamParams, UseCctvRtcStreamReturn } from "../types";
+import type {
+  CctvRtcReconnectTrigger,
+  UseCctvRtcStreamParams,
+  UseCctvRtcStreamReturn,
+} from "../types";
 import { cctvRtcLiveRegistryAtom } from "../jotai/rtc";
 import { getIsLive } from "../utils/video-state";
 import { useFormContext, useWatch } from "react-hook-form";
 
+const AUTO_RECONNECT_INTERVAL_MS = 3000;
+
 /**
  * CCTV 영상 스트림을 WebRTC로 연결하는 커스텀 훅.
  * @hook
@@ -31,7 +37,9 @@ import { useFormContext, useWatch } from "react-hook-form";
  *   isStreaming, // 현재 스트림 연결 절차가 진행 중인지 여부
  *   isTokenLoading, // 토큰 발급 요청이 진행 중인지 여부
  *   isTokenError, // 토큰 발급 요청이 실패했는지 여부
+ *   canReconnect, // 재연결 가능한 종료 상태 여부
  *   refetchToken, // 토큰 발급을 재시도하는 함수
+ *   reconnectStream, // 재연결 trigger 함수
  * }
  */
 export function useCctvRtcStream({
@@ -51,6 +59,7 @@ export function useCctvRtcStream({
   const videoRef = useRef<HTMLVideoElement | null>(null);
   const activeStreamKeyRef = useRef<string | null>(null);
   const activeStreamIdentityKeyRef = useRef<string | null>(null);
+  const lastAutoReconnectAtRef = useRef(0);
 
   // RTCPeerConnectionState를 관찰해 UI에 노출하기 위한 상태값.
   const [connectionState, setConnectionState] =
@@ -61,6 +70,7 @@ export function useCctvRtcStream({
 
   // 현재 스트림 연결 절차가 진행 중인지 여부.
   const [isStreaming, setStreaming] = useState(false);
+  const [hasConnected, setHasConnected] = useState(false);
 
   // react-hook-form 컨텍스트에서 username을 추적한다.
   const { control } = useFormContext();
@@ -74,6 +84,7 @@ export function useCctvRtcStream({
     url: tokenUrl ?? contextTokenUrl,
   });
 
+  const { refetch: refetchRtcToken } = tokenQuery;
   const isTokenLoading = tokenQuery.isFetching;
   const isTokenError = tokenQuery.isError;
 
@@ -111,6 +122,10 @@ export function useCctvRtcStream({
     return [username, cam.company_id, cam.cam_id, endpoint].join("|");
   }, [cam?.cam_id, cam?.company_id, endpoint, username]);
 
+  useEffect(() => {
+    setHasConnected(false);
+  }, [streamIdentityKey]);
+
   // 토큰과 endpoint가 준비되면 WebRTC 스트림을 연결한다.
   useEffect(() => {
     const currentVideo = videoRef.current;
@@ -154,6 +169,7 @@ export function useCctvRtcStream({
       setConnectionState(snapshot.connectionState);
       setStreamError(snapshot.streamError);
       setStreaming(snapshot.isStreaming);
+      if (snapshot.connectionState === "connected") setHasConnected(true);
       if (snapshot.stream && currentVideo.srcObject !== snapshot.stream) {
         currentVideo.srcObject = snapshot.stream;
       }
@@ -162,6 +178,7 @@ export function useCctvRtcStream({
     setConnectionState(snapshot.connectionState);
     setStreamError(snapshot.streamError);
     setStreaming(snapshot.isStreaming);
+    if (snapshot.connectionState === "connected") setHasConnected(true);
 
     if (snapshot.stream && currentVideo.srcObject !== snapshot.stream) {
       currentVideo.srcObject = snapshot.stream;
@@ -182,17 +199,65 @@ export function useCctvRtcStream({
     cam?.cam_online,
   ]);
 
-  const refetchToken = useCallback<typeof tokenQuery.refetch>(
+  const reconnectStream = useCallback<CctvRtcReconnectTrigger>(
     async options => {
-      const result = await tokenQuery.refetch(options);
+      const result = await refetchRtcToken(options);
       if (result.isSuccess && streamIdentityKey) {
         streamRegistry.closeByIdentity(streamIdentityKey);
       }
       return result;
     },
-    [streamIdentityKey, streamRegistry, tokenQuery],
+    [refetchRtcToken, streamIdentityKey, streamRegistry],
   );
 
+  const canReconnect = useMemo(() => {
+    if (!cam?.cam_online) return false;
+    if (!hasConnected) return false;
+    if (!streamIdentityKey) return false;
+    if (isTokenLoading || isStreaming) return false;
+    if (isTokenError || streamError) return true;
+    if (connectionState === "failed") return true;
+    if (connectionState === "disconnected") return true;
+    if (connectionState === "closed") return true;
+    return false;
+  }, [
+    cam?.cam_online,
+    connectionState,
+    hasConnected,
+    isStreaming,
+    isTokenError,
+    isTokenLoading,
+    streamError,
+    streamIdentityKey,
+  ]);
+
+  const refetchToken = reconnectStream;
+
+  useEffect(() => {
+    if (typeof window === "undefined" || typeof document === "undefined")
+      return;
+
+    const reconnectOnFocus = () => {
+      if (document.visibilityState !== "visible") return;
+      if (!canReconnect) return;
+
+      const now = Date.now();
+      if (now - lastAutoReconnectAtRef.current < AUTO_RECONNECT_INTERVAL_MS)
+        return;
+
+      lastAutoReconnectAtRef.current = now;
+      void reconnectStream();
+    };
+
+    window.addEventListener("focus", reconnectOnFocus);
+    document.addEventListener("visibilitychange", reconnectOnFocus);
+
+    return () => {
+      window.removeEventListener("focus", reconnectOnFocus);
+      document.removeEventListener("visibilitychange", reconnectOnFocus);
+    };
+  }, [canReconnect, reconnectStream]);
+
   const liveState = useMemo(
     () =>
       cam
@@ -257,6 +322,8 @@ export function useCctvRtcStream({
     isStreaming,
     isTokenLoading,
     isTokenError,
+    canReconnect,
     refetchToken,
+    reconnectStream,
   };
 }

package/src/cctv/types/hook.ts

@@ -1,4 +1,8 @@
-import type { UseQueryResult } from "@tanstack/react-query";
+import type {
+  QueryObserverResult,
+  RefetchOptions,
+  UseQueryResult,
+} from "@tanstack/react-query";
 import type { API_Res_CctvCompany, API_Res_CctvRtcToken } from "./api";
 import type {
   CctvCompanyCameraData,
@@ -9,6 +13,13 @@ import type {
 import type { UseFormReturn } from "react-hook-form";
 import type { CctvBaseContext } from "./context";
 
+/**
+ * CCTV; RTC stream 재연결 trigger
+ */
+export type CctvRtcReconnectTrigger = (
+  options?: RefetchOptions,
+) => Promise<QueryObserverResult<API_Res_CctvRtcToken>>;
+
 /**
  * CCTV; useCctvRtcStream params
  * @property {CctvCompanyCameraData} [cam] 스트리밍 카메라 정보
@@ -77,17 +88,27 @@ export interface UseCctvRtcStreamState extends UseCctvRtcStreamError {
  * @property {boolean} isStreaming startWhepStream 진행 여부
  * @property {boolean} isTokenLoading 토큰 발급 요청 진행 여부
  * @property {boolean} isTokenError 토큰 발급 실패 여부
+ * @property {boolean} canReconnect 재연결 가능한 종료 상태 여부
  * @property {() => Promise<void>} refetchToken 토큰 재발급 함수
+ * @property {() => Promise<QueryObserverResult<API_Res_CctvRtcToken>>} reconnectStream 재연결 trigger 함수
  */
 export interface UseCctvRtcStreamReturn extends UseCctvRtcStreamState {
   /**
    * <video /> ref
    */
   videoRef: React.RefObject<HTMLVideoElement | null>;
+  /**
+   * 재연결 가능한 종료 상태 여부
+   */
+  canReconnect: boolean;
   /**
    * 토큰 재발급 함수
    */
-  refetchToken: UseQueryResult<API_Res_CctvRtcToken>["refetch"];
+  refetchToken: CctvRtcReconnectTrigger;
+  /**
+   * 재연결 trigger 함수
+   */
+  reconnectStream: CctvRtcReconnectTrigger;
 }
 
 /**

package/src/cctv/types/props.ts

@@ -1,4 +1,5 @@
 import type { CctvCompanyCameraData, CctvCompanyCameraList } from "./list";
+import type { CctvRtcReconnectTrigger } from "./hook";
 
 /**
  * CCTV; custom overlay render context
@@ -8,6 +9,8 @@ import type { CctvCompanyCameraData, CctvCompanyCameraList } from "./list";
  * @property {boolean | undefined} [isError] 영상 에러 상태 여부
  * @property {boolean | undefined} [isLive] 영상 live 상태 여부
  * @property {React.ReactNode} [overlayMessage] 기본 안내/에러 메시지 콘텐츠
+ * @property {boolean | undefined} [canReconnect] 재연결 가능한 종료 상태 여부
+ * @property {CctvRtcReconnectTrigger | undefined} [reconnectStream] 재연결 trigger 함수
  */
 export interface CctvVideoRenderOverlayContext {
   /**
@@ -34,6 +37,14 @@ export interface CctvVideoRenderOverlayContext {
    * 기본 안내/에러 메시지 콘텐츠
    */
   overlayMessage?: React.ReactNode;
+  /**
+   * 재연결 가능한 종료 상태 여부
+   */
+  canReconnect?: boolean;
+  /**
+   * 재연결 trigger 함수
+   */
+  reconnectStream?: CctvRtcReconnectTrigger;
 }
 
 /**
@@ -115,6 +126,8 @@ export interface CctvVideoOverlayFooterProps {
  * @property {boolean} [isError] 에러 상태 여부
  * @property {boolean} [isLive] 영상이 정상적으로 재생 중인지 여부
  * @property {React.ReactNode} [overlayMessage] 에러/안내 메시지 콘텐츠
+ * @property {boolean} [canReconnect] 재연결 가능한 종료 상태 여부
+ * @property {CctvRtcReconnectTrigger} [reconnectStream] 재연결 trigger 함수
  */
 export interface CctvVideoStateProps {
   /**
@@ -129,6 +142,14 @@ export interface CctvVideoStateProps {
    * 오버레이 메시지 콘텐츠
    */
   overlayMessage?: React.ReactNode;
+  /**
+   * 재연결 가능한 종료 상태 여부
+   */
+  canReconnect?: boolean;
+  /**
+   * 재연결 trigger 함수
+   */
+  reconnectStream?: CctvRtcReconnectTrigger;
 }
 
 /**

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

@@ -11,6 +11,7 @@ import type { UseCctvRtcStreamError, UseCctvRtcStreamState } from "./hook";
  * @property {boolean} isTokenLoading 토큰 발급 요청 진행 여부
  * @property {boolean} isTokenError 토큰 발급 실패 여부
  * @property {string | null} streamError 스트림 오류 메시지
+ * @property {boolean} [canReconnect] 재연결 가능한 종료 상태 여부
  */
 export interface CctvVideoOverlayMessageParams extends UseCctvRtcStreamState {
   /**
@@ -25,6 +26,10 @@ export interface CctvVideoOverlayMessageParams extends UseCctvRtcStreamState {
    * 서버에서 cam 리스트를 가져오는 중인지 여부
    */
   isFetching?: boolean;
+  /**
+   * 재연결 가능한 종료 상태 여부
+   */
+  canReconnect?: boolean;
 }
 
 /**
@@ -48,10 +53,15 @@ export interface CctvVideoLiveParams extends UseCctvRtcStreamState {
  * @property {CctvCompanyCameraData} [cam] 카메라 데이터
  * @property {boolean} isTokenError 토큰 발급 실패 여부
  * @property {string | null} streamError 스트림 오류 메시지
+ * @property {boolean} [canReconnect] 재연결 가능한 종료 상태 여부
  */
 export interface CctvVideoErrorParams extends UseCctvRtcStreamError {
   /**
    * 카메라 데이터
    */
   cam?: CctvCompanyCameraData;
+  /**
+   * 재연결 가능한 종료 상태 여부
+   */
+  canReconnect?: boolean;
 }

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

@@ -8,6 +8,8 @@ export const CCTV_MESSAGE = {
   selectCam: "카메라를 선택하세요.",
   fetching: "CCTV 데이터를 불러오는 중입니다.",
   preparing: "스트림을 준비하고 있습니다.",
+  sessionEnded:
+    "장시간 미사용으로 연결이 종료되었습니다. 계속 확인하시려면 다시 연결해 주세요.",
   tokenError: "토큰을 발급하지 못했습니다.",
   offline: "CCTV 연결 오류",
 } as const;
@@ -34,6 +36,7 @@ const RTC_PREPARING_STATES = new Set<RTCPeerConnectionState>([
  */
 export function getOverlayMessage({
   cam,
+  canReconnect,
   connectionState,
   hasCamProp = false,
   isFetching = false,
@@ -48,6 +51,7 @@ export function getOverlayMessage({
   }
 
   if (!cam.cam_online) return CCTV_MESSAGE.offline;
+  if (canReconnect) return CCTV_MESSAGE.sessionEnded;
   // 에러 상태가 준비 상태와 겹칠 때는 에러 문구가 최종 표시 계약을 우선한다.
   if (isTokenError) return CCTV_MESSAGE.tokenError;
   if (streamError) return streamError;
@@ -95,11 +99,13 @@ export function getIsLive({
  */
 export function getIsError({
   cam,
+  canReconnect,
   isTokenError,
   streamError,
 }: CctvVideoErrorParams): boolean {
   if (!cam) return true;
   if (!cam.cam_online) return true;
+  if (canReconnect) return true;
   if (isTokenError) return true;
   if (streamError) return true;
   return false;