@uniai-fe/uds-templates 0.6.6 → 0.6.8

package/dist/styles.css

@@ -1796,6 +1796,22 @@
   flex-direction: column;
   align-items: center;
   justify-content: center;
+  gap: 2px;
+}
+
+.cctv-video-loading-icon {
+  flex: 0 0 auto;
+  width: 24px;
+  height: 24px;
+  display: flex;
+  color: var(--cctv-error-text-color);
+}
+.cctv-video-loading-icon .alternate-loading-icon {
+  width: 24px;
+  height: 24px;
+}
+.cctv-video-loading-icon svg stop:first-child {
+  stop-color: currentColor;
 }
 
 .cctv-video-error-icon {
@@ -1806,11 +1822,17 @@
 
 .cctv-video-error-message {
   font-size: 13px;
-  color: var(--cctv-status-text-color);
+  color: var(--cctv-error-text-color);
   line-height: 1.5em;
   font-weight: 500;
 }
 
+.cctv-video-overlay-body.is-error .cctv-video-error {
+  gap: 0;
+}
+.cctv-video-overlay-body.is-error .cctv-video-loading-icon {
+  display: none;
+}
 .cctv-video-overlay-body.is-error .cctv-video-error-icon {
   display: block;
 }

package/package.json

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

package/src/cctv/components/video/overlay/body/Error.tsx

@@ -1,3 +1,4 @@
+import { Alternate } from "@uniai-fe/uds-primitives";
 import CCTVErrorIcon from "../../../../img/error.svg";
 
 export default function CCTVVideoError({
@@ -7,6 +8,9 @@ export default function CCTVVideoError({
 }) {
   return (
     <div className="cctv-video-error">
+      <span className="cctv-video-loading-icon" aria-hidden="true">
+        <Alternate.LoadingIcon size="small" />
+      </span>
       <figure className="cctv-video-error-icon">
         <CCTVErrorIcon width={24} height={24} />
       </figure>

package/src/cctv/hooks/useRtcStream.ts

@@ -23,8 +23,65 @@ import { getIsLive } from "../utils/video-state";
 import { useFormContext, useWatch } from "react-hook-form";
 
 const AUTO_RECONNECT_INTERVAL_MS = 3000;
+const POST_CONNECTED_RECONNECT_GRACE_MS = 5000;
+const POST_CONNECTED_RECONNECT_STAGGER_MS = 5000;
 const TOKEN_EXPIRY_SAFETY_MS = 30 * 1000;
 
+type CctvRtcReconnectReason =
+  | "tokenError"
+  | "streamError"
+  | "failed"
+  | "disconnected";
+
+const DISPLAY_CONNECTED_DURING_GRACE_STATES = new Set<RTCPeerConnectionState>([
+  "disconnected",
+  "failed",
+]);
+
+/**
+ * 같은 회사/카메라 묶음이 동시에 재연결하지 않도록 identity 기반 지연값을 만든다.
+ * @desc
+ * 이 값은 보안용 난수가 아니라 UI/네트워크 부하를 분산하기 위한 안정 해시다.
+ */
+const getStableStaggerMs = (value: string): number => {
+  let hash = 0;
+
+  for (let i = 0; i < value.length; i += 1) {
+    hash =
+      (hash * 31 + value.charCodeAt(i)) % POST_CONNECTED_RECONNECT_STAGGER_MS;
+  }
+
+  return hash;
+};
+
+/**
+ * 최초 연결 이후 끊김/실패가 감지됐을 때 자동 재연결 노출 전 대기시간을 계산한다.
+ */
+const getPostConnectedReconnectDelayMs = (delayKey: string): number =>
+  POST_CONNECTED_RECONNECT_GRACE_MS + getStableStaggerMs(delayKey);
+
+/**
+ * 재연결이 필요한 장애 사유를 UDS 내부 기준으로 정규화한다.
+ * @desc
+ * `closed`는 `streamRegistry.closeByIdentity()`처럼 UDS가 의도적으로 닫을 때도 발생하므로
+ * 자동 재연결 사유에 포함하지 않는다.
+ */
+const getPostConnectedReconnectReason = ({
+  connectionState,
+  isTokenError,
+  streamError,
+}: {
+  connectionState: RTCPeerConnectionState;
+  isTokenError: boolean;
+  streamError: string | null;
+}): CctvRtcReconnectReason | null => {
+  if (isTokenError) return "tokenError";
+  if (streamError) return "streamError";
+  if (connectionState === "failed") return "failed";
+  if (connectionState === "disconnected") return "disconnected";
+  return null;
+};
+
 const decodeBase64Url = (value: string): string | null => {
   try {
     const base64 = value.replace(/-/g, "+").replace(/_/g, "/");
@@ -86,7 +143,7 @@ const canUseTokenForNewConnection = ({
  *   isStreaming, // 현재 스트림 연결 절차가 진행 중인지 여부
  *   isTokenLoading, // 토큰 발급 요청이 진행 중인지 여부
  *   isTokenError, // 토큰 발급 요청이 실패했는지 여부
- *   canReconnect, // 재연결 가능한 종료 상태 여부
+ *   canReconnect, // UDS 내부 grace/stagger 이후 재연결 호출이 가능한지 여부
  *   refetchToken, // 토큰 발급을 재시도하는 함수
  *   reconnectStream, // 재연결 trigger 함수
  * }
@@ -121,6 +178,8 @@ export function useCctvRtcStream({
   // 현재 스트림 연결 절차가 진행 중인지 여부.
   const [isStreaming, setStreaming] = useState(false);
   const [hasConnected, setHasConnected] = useState(false);
+  const [isPostConnectedReconnectReady, setPostConnectedReconnectReady] =
+    useState(false);
 
   // react-hook-form 컨텍스트에서 token username과 WHEP username override를 추적한다.
   const { control } = useFormContext();
@@ -181,6 +240,60 @@ export function useCctvRtcStream({
     setHasConnected(false);
   }, [streamIdentityKey]);
 
+  const reconnectReason = useMemo(
+    () =>
+      getPostConnectedReconnectReason({
+        connectionState,
+        isTokenError,
+        streamError,
+      }),
+    [connectionState, isTokenError, streamError],
+  );
+
+  useEffect(() => {
+    const canStartReconnectTimer =
+      hasConnected &&
+      Boolean(streamIdentityKey) &&
+      Boolean(reconnectReason) &&
+      !isTokenLoading &&
+      !isStreaming;
+
+    if (!canStartReconnectTimer) {
+      setPostConnectedReconnectReady(false);
+      return;
+    }
+
+    setPostConnectedReconnectReady(false);
+
+    const timeout = setTimeout(
+      () => {
+        setPostConnectedReconnectReady(true);
+      },
+      getPostConnectedReconnectDelayMs(
+        `${streamIdentityKey}|${reconnectReason}`,
+      ),
+    );
+
+    return () => {
+      clearTimeout(timeout);
+    };
+  }, [
+    hasConnected,
+    isStreaming,
+    isTokenLoading,
+    reconnectReason,
+    streamIdentityKey,
+  ]);
+
+  const shouldPreserveConnectedDisplay =
+    hasConnected &&
+    !isPostConnectedReconnectReady &&
+    DISPLAY_CONNECTED_DURING_GRACE_STATES.has(connectionState);
+
+  const displayConnectionState = shouldPreserveConnectedDisplay
+    ? "connected"
+    : connectionState;
+
   const hasReusableRegistryStream = useMemo(() => {
     if (!streamKeyCandidate) return false;
 
@@ -329,19 +442,15 @@ export function useCctvRtcStream({
     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;
+    if (!reconnectReason) return false;
+    return isPostConnectedReconnectReady;
   }, [
     cam?.cam_online,
-    connectionState,
     hasConnected,
+    isPostConnectedReconnectReady,
     isStreaming,
-    isTokenError,
     isTokenLoading,
-    streamError,
+    reconnectReason,
     streamIdentityKey,
   ]);
 
@@ -377,7 +486,7 @@ export function useCctvRtcStream({
       cam
         ? getIsLive({
             cam,
-            connectionState,
+            connectionState: displayConnectionState,
             isTokenLoading,
             isTokenError,
             isStreaming,
@@ -386,7 +495,7 @@ export function useCctvRtcStream({
         : false,
     [
       cam,
-      connectionState,
+      displayConnectionState,
       isTokenLoading,
       isTokenError,
       isStreaming,
@@ -431,7 +540,7 @@ export function useCctvRtcStream({
   // 호출자에게 video ref와 상태값, 토큰 쿼리 상태를 전달한다.
   return {
     videoRef,
-    connectionState,
+    connectionState: displayConnectionState,
     streamError,
     isStreaming,
     isTokenLoading,

package/src/cctv/styles/video.scss

@@ -137,6 +137,23 @@
   flex-direction: column;
   align-items: center;
   justify-content: center;
+  gap: 2px;
+}
+.cctv-video-loading-icon {
+  flex: 0 0 auto;
+  width: 24px;
+  height: 24px;
+  display: flex;
+  color: var(--cctv-error-text-color);
+
+  .alternate-loading-icon {
+    width: 24px;
+    height: 24px;
+  }
+
+  svg stop:first-child {
+    stop-color: currentColor;
+  }
 }
 .cctv-video-error-icon {
   display: none;
@@ -145,12 +162,20 @@
 }
 .cctv-video-error-message {
   font-size: 13px;
-  color: var(--cctv-status-text-color);
+  color: var(--cctv-error-text-color);
   line-height: 1.5em;
   font-weight: 500;
 }
 
 .cctv-video-overlay-body.is-error {
+  .cctv-video-error {
+    gap: 0;
+  }
+
+  .cctv-video-loading-icon {
+    display: none;
+  }
+
   .cctv-video-error-icon {
     display: block;
   }

package/src/cctv/types/hook.ts

@@ -88,7 +88,7 @@ export interface UseCctvRtcStreamState extends UseCctvRtcStreamError {
  * @property {boolean} isStreaming startWhepStream 진행 여부
  * @property {boolean} isTokenLoading 토큰 발급 요청 진행 여부
  * @property {boolean} isTokenError 토큰 발급 실패 여부
- * @property {boolean} canReconnect 재연결 가능한 종료 상태 여부
+ * @property {boolean} canReconnect UDS 내부 grace/stagger를 통과해 재연결 호출이 가능한지 여부
  * @property {() => Promise<void>} refetchToken 토큰 재발급 함수
  * @property {() => Promise<QueryObserverResult<API_Res_CctvRtcToken>>} reconnectStream 재연결 trigger 함수
  */
@@ -98,7 +98,10 @@ export interface UseCctvRtcStreamReturn extends UseCctvRtcStreamState {
    */
   videoRef: React.RefObject<HTMLVideoElement | null>;
   /**
-   * 재연결 가능한 종료 상태 여부
+   * UDS 내부 grace/stagger를 통과해 재연결 호출이 가능한지 여부
+   * @desc
+   * 스트림 장애 감지 즉시 true가 되는 플래그가 아니라,
+   * 서비스 overlay가 reconnectStream()을 호출해도 되는 시점에 true가 된다.
    */
   canReconnect: boolean;
   /**

package/src/cctv/types/props.ts

@@ -9,7 +9,7 @@ import type { CctvRtcReconnectTrigger } from "./hook";
  * @property {boolean | undefined} [isError] 영상 에러 상태 여부
  * @property {boolean | undefined} [isLive] 영상 live 상태 여부
  * @property {React.ReactNode} [overlayMessage] 기본 안내/에러 메시지 콘텐츠
- * @property {boolean | undefined} [canReconnect] 재연결 가능한 종료 상태 여부
+ * @property {boolean | undefined} [canReconnect] UDS 내부 grace/stagger를 통과해 재연결 호출이 가능한지 여부
  * @property {CctvRtcReconnectTrigger | undefined} [reconnectStream] 재연결 trigger 함수
  */
 export interface CctvVideoRenderOverlayContext {
@@ -38,7 +38,10 @@ export interface CctvVideoRenderOverlayContext {
    */
   overlayMessage?: React.ReactNode;
   /**
-   * 재연결 가능한 종료 상태 여부
+   * UDS 내부 grace/stagger를 통과해 재연결 호출이 가능한지 여부
+   * @desc
+   * custom overlay에서 자동 재연결을 구현할 때 이 값이 true인 경우에만
+   * reconnectStream()을 호출해야 한다.
    */
   canReconnect?: boolean;
   /**
@@ -126,7 +129,7 @@ export interface CctvVideoOverlayFooterProps {
  * @property {boolean} [isError] 에러 상태 여부
  * @property {boolean} [isLive] 영상이 정상적으로 재생 중인지 여부
  * @property {React.ReactNode} [overlayMessage] 에러/안내 메시지 콘텐츠
- * @property {boolean} [canReconnect] 재연결 가능한 종료 상태 여부
+ * @property {boolean} [canReconnect] UDS 내부 grace/stagger를 통과해 재연결 호출이 가능한지 여부
  * @property {CctvRtcReconnectTrigger} [reconnectStream] 재연결 trigger 함수
  */
 export interface CctvVideoStateProps {
@@ -143,7 +146,7 @@ export interface CctvVideoStateProps {
    */
   overlayMessage?: React.ReactNode;
   /**
-   * 재연결 가능한 종료 상태 여부
+   * UDS 내부 grace/stagger를 통과해 재연결 호출이 가능한지 여부
    */
   canReconnect?: boolean;
   /**

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

@@ -11,7 +11,7 @@ import type { UseCctvRtcStreamError, UseCctvRtcStreamState } from "./hook";
  * @property {boolean} isTokenLoading 토큰 발급 요청 진행 여부
  * @property {boolean} isTokenError 토큰 발급 실패 여부
  * @property {string | null} streamError 스트림 오류 메시지
- * @property {boolean} [canReconnect] 재연결 가능한 종료 상태 여부
+ * @property {boolean} [canReconnect] UDS 내부 grace/stagger를 통과해 재연결 호출이 가능한지 여부
  */
 export interface CctvVideoOverlayMessageParams extends UseCctvRtcStreamState {
   /**
@@ -27,7 +27,7 @@ export interface CctvVideoOverlayMessageParams extends UseCctvRtcStreamState {
    */
   isFetching?: boolean;
   /**
-   * 재연결 가능한 종료 상태 여부
+   * UDS 내부 grace/stagger를 통과해 재연결 호출이 가능한지 여부
    */
   canReconnect?: boolean;
 }
@@ -53,7 +53,7 @@ export interface CctvVideoLiveParams extends UseCctvRtcStreamState {
  * @property {CctvCompanyCameraData} [cam] 카메라 데이터
  * @property {boolean} isTokenError 토큰 발급 실패 여부
  * @property {string | null} streamError 스트림 오류 메시지
- * @property {boolean} [canReconnect] 재연결 가능한 종료 상태 여부
+ * @property {boolean} [canReconnect] UDS 내부 grace/stagger를 통과해 재연결 호출이 가능한지 여부
  */
 export interface CctvVideoErrorParams extends UseCctvRtcStreamError {
   /**
@@ -61,7 +61,7 @@ export interface CctvVideoErrorParams extends UseCctvRtcStreamError {
    */
   cam?: CctvCompanyCameraData;
   /**
-   * 재연결 가능한 종료 상태 여부
+   * UDS 내부 grace/stagger를 통과해 재연결 호출이 가능한지 여부
    */
   canReconnect?: boolean;
 }

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

@@ -62,6 +62,10 @@ export function getOverlayMessage({
   if (canReconnect && RTC_SESSION_ENDED_RECONNECT_STATES.has(connectionState)) {
     return CCTV_MESSAGE.sessionEnded;
   }
+  // grace/stagger가 끝난 disconnected는 더 이상 준비 상태가 아니라 재연결 대상 장애다.
+  if (canReconnect && connectionState === "disconnected") {
+    return CCTV_MESSAGE.offline;
+  }
   if (isTokenLoading || isStreaming) return CCTV_MESSAGE.preparing;
   if (RTC_PREPARING_STATES.has(connectionState)) return CCTV_MESSAGE.preparing;
   return null;