@uniai-fe/uds-templates 0.6.14 → 0.6.15

package/package.json

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

package/src/cctv/hooks/useRtcStream.ts

@@ -138,7 +138,7 @@ const canUseTokenForNewConnection = ({
  * @desc
  * return {
  *   videoRef, // WebRTC MediaStream을 연결할 video 요소 ref
- *   connectionState, // RTCPeerConnectionState 상태값
+ *   connectionState, // UI 표시 기준 RTCPeerConnectionState 상태값
  *   streamError, // 스트림 시도 중 발생한 오류 메시지
  *   isStreaming, // UI 표시 기준 스트림 연결 절차 진행 여부
  *   isTokenLoading, // UI 표시 기준 토큰 발급 요청 진행 여부
@@ -328,6 +328,13 @@ export function useCctvRtcStream({
     streamIdentityKey,
   ]);
 
+  const isPostConnectedRecoverableState =
+    hasConnected &&
+    Boolean(streamIdentityKey) &&
+    !isTokenError &&
+    !streamError &&
+    DISPLAY_CONNECTED_DURING_RECOVERY_STATES.has(connectionState);
+
   const isPostConnectedReplacementLoading =
     hasConnected &&
     Boolean(streamIdentityKey) &&
@@ -336,13 +343,10 @@ export function useCctvRtcStream({
     (isTokenLoading || isStreaming);
 
   const shouldPreserveConnectedDisplay =
-    isPostConnectedReplacementLoading ||
-    (hasConnected &&
-      !isPostConnectedReconnectReady &&
-      DISPLAY_CONNECTED_DURING_RECOVERY_STATES.has(connectionState));
+    isPostConnectedReplacementLoading || isPostConnectedRecoverableState;
 
   // 반환 state는 CamList/Viewer/overlay의 live/error/message 계산에 직접 쓰인다.
-  // post-connected recovery/replacement 중에는 기존 화면을 유지해 UI reset 파동을 막는다.
+  // post-connected recovery/replacement 중에는 canReconnect만 열고, 기존 화면은 유지해 UI reset 파동을 막는다.
   const displayConnectionState = shouldPreserveConnectedDisplay
     ? "connected"
     : connectionState;
@@ -738,6 +742,7 @@ export function useCctvRtcStream({
         displayConnectionState,
         hasConnected,
         isPostConnectedReplacementLoading,
+        isPostConnectedRecoverableState,
         isPostConnectedReconnectReady,
         displayIsStreaming,
         displayIsTokenLoading,
@@ -759,6 +764,7 @@ export function useCctvRtcStream({
     displayIsTokenLoading,
     hasConnected,
     isPostConnectedReplacementLoading,
+    isPostConnectedRecoverableState,
     isPostConnectedReconnectReady,
     isStreaming,
     isTokenError,

package/src/cctv/types/hook.ts

@@ -59,7 +59,7 @@ export interface UseCctvRtcStreamError {
 
 /**
  * CCTV; useCctvRtcStream 연결 상태
- * @property {RTCPeerConnectionState} connectionState WebRTC 연결 상태
+ * @property {RTCPeerConnectionState} connectionState UI 표시 기준 WebRTC 연결 상태
  * @property {boolean} isStreaming UI 표시 기준 startWhepStream 진행 여부
  * @property {boolean} isTokenLoading UI 표시 기준 토큰 발급 요청 진행 여부
  * @property {boolean} isTokenError 토큰 발급 실패 여부
@@ -67,7 +67,11 @@ export interface UseCctvRtcStreamError {
  */
 export interface UseCctvRtcStreamState extends UseCctvRtcStreamError {
   /**
-   * WebRTC 연결 상태
+   * UI 표시 기준 WebRTC 연결 상태
+   * @desc
+   * 최초 연결 전에는 실제 PeerConnection 상태를 나타낸다. 이미 한 번 연결된 stream이
+   * recoverable `disconnected`/`failed` 상태에 들어가면 기존 화면과 live count 유지를 위해
+   * `connected`로 smoothing될 수 있다.
    */
   connectionState: RTCPeerConnectionState;
   /**
@@ -89,7 +93,7 @@ export interface UseCctvRtcStreamState extends UseCctvRtcStreamError {
 /**
  * CCTV; useCctvRtcStream return
  * @property {React.RefObject<HTMLVideoElement>} videoRef <video /> ref
- * @property {RTCPeerConnectionState} connectionState WebRTC 연결 상태
+ * @property {RTCPeerConnectionState} connectionState UI 표시 기준 WebRTC 연결 상태
  * @property {string | null} streamError 스트림 오류 메시지
  * @property {boolean} isStreaming UI 표시 기준 startWhepStream 진행 여부
  * @property {boolean} isTokenLoading UI 표시 기준 토큰 발급 요청 진행 여부
@@ -110,6 +114,7 @@ export interface UseCctvRtcStreamReturn extends UseCctvRtcStreamState {
    * 서비스 overlay가 reconnectStream()을 호출해도 되는 시점에 true가 된다.
    * post-connected `disconnected`는 자동 재연결 사유가 아니며,
    * token/stream 오류 또는 `failed`처럼 명확한 복구 사유만 true 전환 후보가 된다.
+   * recoverable `failed`에서는 화면이 live로 유지되는 동안에도 true가 될 수 있다.
    */
   canReconnect: boolean;
   /**

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

@@ -6,12 +6,13 @@ import type { UseCctvRtcStreamError, UseCctvRtcStreamState } from "./hook";
  * @property {CctvCompanyCameraData} [cam] 카메라 데이터
  * @property {boolean} [hasCamProp] 직접 cam prop을 받은 경우 true
  * @property {boolean} [isFetching] 서버에서 cam 리스트를 가져오는 중인지 여부
- * @property {RTCPeerConnectionState} connectionState WebRTC 연결 상태
+ * @property {RTCPeerConnectionState} connectionState UI 표시 기준 WebRTC 연결 상태
  * @property {boolean} isStreaming UI 표시 기준 startWhepStream 진행 여부
  * @property {boolean} isTokenLoading UI 표시 기준 토큰 발급 요청 진행 여부
  * @property {boolean} isTokenError 토큰 발급 실패 여부
  * @property {string | null} streamError 스트림 오류 메시지
- * @property {boolean} [canReconnect] UDS 내부 허용 사유와 grace/stagger를 통과해 재연결 호출이 가능한지 여부
+ * @property {boolean} [canReconnect] UDS 내부 허용 사유와 grace/stagger를 통과해 재연결 호출이 가능한지 여부.
+ * 오류 스타일 판정에는 직접 사용하지 않는다.
  */
 export interface CctvVideoOverlayMessageParams extends UseCctvRtcStreamState {
   /**
@@ -28,6 +29,8 @@ export interface CctvVideoOverlayMessageParams extends UseCctvRtcStreamState {
   isFetching?: boolean;
   /**
    * UDS 내부 허용 사유와 grace/stagger를 통과해 재연결 호출이 가능한지 여부
+   * @desc
+   * 재연결 trigger gate이며, 기본 error style 판정에는 직접 사용하지 않는다.
    */
   canReconnect?: boolean;
 }
@@ -35,7 +38,7 @@ export interface CctvVideoOverlayMessageParams extends UseCctvRtcStreamState {
 /**
  * CCTV; getIsLive() params
  * @property {CctvCompanyCameraData} [cam] 카메라 데이터
- * @property {RTCPeerConnectionState} connectionState WebRTC 연결 상태
+ * @property {RTCPeerConnectionState} connectionState UI 표시 기준 WebRTC 연결 상태
  * @property {boolean} isStreaming UI 표시 기준 startWhepStream 진행 여부
  * @property {boolean} isTokenLoading UI 표시 기준 토큰 발급 요청 진행 여부
  * @property {boolean} isTokenError 토큰 발급 실패 여부
@@ -53,7 +56,8 @@ export interface CctvVideoLiveParams extends UseCctvRtcStreamState {
  * @property {CctvCompanyCameraData} [cam] 카메라 데이터
  * @property {boolean} isTokenError 토큰 발급 실패 여부
  * @property {string | null} streamError 스트림 오류 메시지
- * @property {boolean} [canReconnect] UDS 내부 허용 사유와 grace/stagger를 통과해 재연결 호출이 가능한지 여부
+ * @property {boolean} [canReconnect] UDS 내부 허용 사유와 grace/stagger를 통과해 재연결 호출이 가능한지 여부.
+ * 오류 스타일 판정에는 직접 사용하지 않는다.
  */
 export interface CctvVideoErrorParams extends UseCctvRtcStreamError {
   /**
@@ -62,6 +66,8 @@ export interface CctvVideoErrorParams extends UseCctvRtcStreamError {
   cam?: CctvCompanyCameraData;
   /**
    * UDS 내부 허용 사유와 grace/stagger를 통과해 재연결 호출이 가능한지 여부
+   * @desc
+   * 재연결 trigger gate이며, 기본 error style 판정에는 직접 사용하지 않는다.
    */
   canReconnect?: boolean;
 }

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

@@ -31,7 +31,7 @@ const RTC_SESSION_ENDED_RECONNECT_STATES = new Set<RTCPeerConnectionState>([
  * @property {CctvCompanyCameraData} [cam] 카메라 데이터
  * @property {boolean} [hasCamProp] 직접 cam prop을 받은 경우 true
  * @property {boolean} [isFetching] 서버에서 cam 리스트를 가져오는 중인지 여부
- * @property {RTCPeerConnectionState} connectionState WebRTC 연결 상태
+ * @property {RTCPeerConnectionState} connectionState UI 표시 기준 WebRTC 연결 상태
  * @property {boolean} isStreaming UI 표시 기준 startWhepStream 진행 여부
  * @property {boolean} isTokenLoading UI 표시 기준 토큰 발급 요청 진행 여부
  * @property {boolean} isTokenError 토큰 발급 실패 여부
@@ -72,7 +72,7 @@ export function getOverlayMessage({
  * CCTV; 스트리밍 라이브 상태 판단
  * @param {CctvVideoLiveParams} params 상태 파라미터
  * @property {CctvCompanyCameraData} [cam] 카메라 데이터
- * @property {RTCPeerConnectionState} connectionState WebRTC 연결 상태
+ * @property {RTCPeerConnectionState} connectionState UI 표시 기준 WebRTC 연결 상태
  * @property {boolean} isStreaming UI 표시 기준 startWhepStream 진행 여부
  * @property {boolean} isTokenLoading UI 표시 기준 토큰 발급 요청 진행 여부
  * @property {boolean} isTokenError 토큰 발급 실패 여부
@@ -102,17 +102,16 @@ export function getIsLive({
  * @property {CctvCompanyCameraData} [cam] 카메라 데이터
  * @property {boolean} isTokenError 토큰 발급 실패 여부
  * @property {string | null} streamError 스트림 오류 메시지
+ * @property {boolean} [canReconnect] 재연결 trigger 가능 여부. 오류 표시 여부에는 직접 사용하지 않는다.
  * @returns {boolean} 에러 상태 여부 반환
  */
 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;