@uniai-fe/uds-templates 0.6.26 → 0.6.28

package/dist/styles.css

@@ -94,6 +94,7 @@
   /* Card layout */
   --cctv-video-radius: 12px;
   --cctv-list-gap: var(--spacing-gap-5);
+  --cctv-list-item-min-width: 320px;
   --cctv-overlay-padding-x: var(--spacing-padding-8);
   --cctv-overlay-padding-y: var(--spacing-padding-6);
   --cctv-video-bg: var(--color-surface-heavy);
@@ -1873,6 +1874,7 @@
 }
 
 .cctv-cam-list-container {
+  container: cctv-cam-list/inline-size;
   width: 100%;
   height: 100%;
   overflow-x: hidden;
@@ -1888,7 +1890,7 @@
 .cctv-cam-list-track {
   display: grid;
   width: 100%;
-  grid-template-columns: repeat(auto-fit, minmax(320px, 1fr));
+  grid-template-columns: repeat(auto-fit, minmax(min(100%, var(--cctv-list-item-min-width)), 1fr));
   gap: var(--cctv-list-gap);
   padding: 0;
   margin: 0;
@@ -1902,6 +1904,26 @@
   max-height: 240px;
 }
 
+@container cctv-cam-list (min-width: 652px) {
+  .cctv-cam-list-track {
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+  }
+}
+@container cctv-cam-list (min-width: 984px) {
+  .cctv-cam-list-track {
+    grid-template-columns: repeat(3, minmax(0, 1fr));
+  }
+}
+@container cctv-cam-list (min-width: 1316px) {
+  .cctv-cam-list-track {
+    grid-template-columns: repeat(4, minmax(0, 1fr));
+  }
+}
+@container cctv-cam-list (min-width: 1648px) {
+  .cctv-cam-list-track {
+    grid-template-columns: repeat(5, minmax(0, 1fr));
+  }
+}
 .cctv-pagination-container {
   width: 100%;
   display: flex;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniai-fe/uds-templates",
-  "version": "0.6.26",
+  "version": "0.6.28",
   "description": "UNIAI Design System; UI Templates Package",
   "type": "module",
   "private": false,
@@ -72,9 +72,9 @@
   },
   "devDependencies": {
     "@svgr/webpack": "^8.1.0",
-    "@tanstack/react-query": "^5.101.0",
+    "@tanstack/react-query": "^5.101.1",
     "@types/node": "^24.12.3",
-    "@types/react": "^19.2.16",
+    "@types/react": "^19.2.17",
     "@types/react-dom": "^19.2.3",
     "@uniai-fe/eslint-config": "workspace:*",
     "@uniai-fe/next-devkit": "workspace:*",
@@ -88,11 +88,11 @@
     "@uniai-fe/util-next": "workspace:*",
     "@uniai-fe/util-rtc": "workspace:*",
     "eslint": "^9.39.2",
-    "jotai": "^2.20.0",
+    "jotai": "^2.20.1",
     "next": "^15.5.18",
-    "prettier": "^3.8.3",
-    "react-hook-form": "^7.77.0",
-    "sass": "^1.100.0",
+    "prettier": "^3.8.4",
+    "react-hook-form": "^7.80.0",
+    "sass": "^1.101.0",
     "typescript": "5.9.3"
   }
 }

package/src/cctv/apis/client.ts

@@ -1,22 +1,129 @@
 "use client";
 
 import { useQuery, type UseQueryResult } from "@tanstack/react-query";
+import { getApiError } from "@uniai-fe/util-api";
 import type {
   API_Req_CctvRtcToken,
   API_Res_CctvCompany,
   API_Res_CctvRtcToken,
 } from "../types";
 
+/**
+ * CCTV; RTC token fallback max age
+ * @desc
+ * JWT exp를 읽을 수 없는 token은 React Query dataUpdatedAt 기준으로 이 시간까지만 신규 WHEP 연결에 재사용한다.
+ */
 export const CCTV_RTC_TOKEN_FALLBACK_MAX_AGE_MS = 5 * 60 * 1000;
+
+/**
+ * CCTV; RTC token query cache retention
+ * @desc
+ * focus/reconnect 자동 refetch는 막되, 오래된 token이 무기한 신규 연결에 쓰이지 않게 fallback max age와 동일하게 제한한다.
+ */
 export const CCTV_RTC_TOKEN_GC_TIME_MS = CCTV_RTC_TOKEN_FALLBACK_MAX_AGE_MS;
 
+/**
+ * CCTV; RTC token request error
+ * @property {number} [statusCode] service token route HTTP status
+ * @desc
+ * fetch 성공 여부와 API payload 실패 여부를 React Query error 상태로 통일하기 위한 내부 error다.
+ */
+class CctvRtcTokenRequestError extends Error {
+  readonly statusCode?: number;
+
+  constructor(message: string, statusCode?: number) {
+    super(message);
+    this.name = "CctvRtcTokenRequestError";
+    this.statusCode = statusCode;
+  }
+}
+
+/**
+ * CCTV; RTC token direct response guard
+ * @param {unknown} payload 검사할 token response payload
+ * @returns {payload is API_Res_CctvRtcToken} direct `{ token }` 응답 여부
+ */
+const isCctvRtcTokenResponse = (
+  payload: unknown,
+): payload is API_Res_CctvRtcToken => {
+  if (!payload || typeof payload !== "object") {
+    return false;
+  }
+
+  const nextPayload = payload as Partial<API_Res_CctvRtcToken>;
+
+  return (
+    typeof nextPayload.token === "string" && nextPayload.token.trim() !== ""
+  );
+};
+
+/**
+ * CCTV; RTC token payload normalizer
+ * @param {unknown} payload service token route 응답 payload
+ * @returns {API_Res_CctvRtcToken | null} 사용 가능한 token 응답
+ * @desc
+ * service route가 direct `{ token }` 또는 API base `{ data: { token } }`를 반환하는 경우를 모두 소비한다.
+ */
+const getCctvRtcTokenResponse = (
+  payload: unknown,
+): API_Res_CctvRtcToken | null => {
+  if (isCctvRtcTokenResponse(payload)) {
+    return payload;
+  }
+
+  if (!payload || typeof payload !== "object") {
+    return null;
+  }
+
+  const nextPayload = payload as { data?: unknown };
+
+  return isCctvRtcTokenResponse(nextPayload.data) ? nextPayload.data : null;
+};
+
+/**
+ * CCTV; RTC token query retry policy
+ * @param {number} failureCount 현재 실패 횟수
+ * @param {Error} error queryFn에서 throw된 error
+ * @returns {boolean} 재시도 여부
+ * @desc
+ * 인증/권한/config/응답 계약 오류는 재시도하지 않고, 5xx 또는 network error만 1회 재시도한다.
+ */
+const shouldRetryCctvRtcTokenQuery = (
+  failureCount: number,
+  error: Error,
+): boolean => {
+  if (
+    error instanceof CctvRtcTokenRequestError &&
+    (error.statusCode === undefined || error.statusCode < 500)
+  ) {
+    return false;
+  }
+
+  return failureCount < 1;
+};
+
+/**
+ * CCTV; client company-list fetcher
+ * @param {object} params 요청 파라미터
+ * @param {string} [params.url] service에서 주입한 company-list API 경로
+ * @returns {Promise<API_Res_CctvCompany>} CCTV company-list 응답
+ */
 export const getClientCctvCompanyList = async ({
   url,
 }: {
   url?: string;
 }): Promise<API_Res_CctvCompany> =>
+  // Provider에서 listUrl을 주입하지 않으면 UDS 기본 Next route를 사용한다.
   await (await fetch(url ?? "/api/cctv/company-list")).json();
 
+/**
+ * CCTV; company-list query hook
+ * @hook
+ * @param {object} params query 파라미터
+ * @param {string} [params.url] service에서 주입한 company-list API 경로
+ * @param {readonly unknown[]} [params.queryKeyDeps] service별 목록 cache 분리용 key dependency
+ * @returns {UseQueryResult<API_Res_CctvCompany>} company-list query 결과
+ */
 export const useQueryCctvCompanyList = ({
   url,
   queryKeyDeps = [],
@@ -25,40 +132,95 @@ export const useQueryCctvCompanyList = ({
   queryKeyDeps?: readonly unknown[];
 }): UseQueryResult<API_Res_CctvCompany> =>
   useQuery({
+    // username/site 등 service-local 조건이 바뀌면 queryKeyDeps로 cache를 분리한다.
     queryKey: ["cctv_company_list", url, ...queryKeyDeps],
     queryFn: () => getClientCctvCompanyList({ url }),
   });
 
+/**
+ * CCTV; RTC token POST fetcher
+ * @param {API_Req_CctvRtcToken & { url?: string }} params token 요청 파라미터
+ * @param {string} params.company_id 업체 id코드
+ * @param {string} params.cam_id 카메라 id코드
+ * @param {string} params.username CCTV token 권한 확인용 계정명
+ * @param {string} [params.url] service에서 주입한 token API 경로
+ * @returns {Promise<API_Res_CctvRtcToken>} RTC token 응답
+ * @desc
+ * - UDS는 기본 token route로 fallback하지 않고 service가 주입한 `url`만 호출한다.
+ * - body의 `company_id`, `cam_id`, `username`은 token route가 권한 검증에 사용할 client-visible 식별자다.
+ * - service route는 이 값을 신뢰하지 말고 authenticated session 기준으로 접근 권한을 재검증해야 한다.
+ */
 export const postCctvRtcToken = async ({
   company_id,
   cam_id,
   username,
   url,
-}: API_Req_CctvRtcToken & { url?: string }): Promise<API_Res_CctvRtcToken> =>
-  await (
-    await fetch(url ?? "/api/cctv/token", {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-      },
-      body: JSON.stringify({ company_id, cam_id, username }),
-    })
-  ).json();
+}: API_Req_CctvRtcToken & { url?: string }): Promise<API_Res_CctvRtcToken> => {
+  if (!url) {
+    throw new CctvRtcTokenRequestError("CCTV token URL is required.");
+  }
+
+  const response = await fetch(url, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({ company_id, cam_id, username }),
+  });
+  const payload: unknown = await response.json().catch(() => undefined);
+  const apiError = getApiError(response, payload);
+
+  if (apiError) {
+    throw new CctvRtcTokenRequestError(
+      apiError.message ?? "CCTV token request failed.",
+      apiError.code,
+    );
+  }
+
+  const tokenResponse = getCctvRtcTokenResponse(payload);
+
+  if (!tokenResponse) {
+    throw new CctvRtcTokenRequestError(
+      "CCTV token response is missing token.",
+      response.status,
+    );
+  }
+
+  return tokenResponse;
+};
 
+/**
+ * CCTV; RTC token query hook
+ * @hook
+ * @param {API_Req_CctvRtcToken & { enabled?: boolean; url?: string }} params token query 파라미터
+ * @param {string} params.company_id 업체 id코드
+ * @param {string} params.cam_id 카메라 id코드
+ * @param {boolean} [params.enabled] scheduler grant 이후 token query를 열기 위한 외부 gate
+ * @param {string} params.username CCTV token 권한 확인용 계정명
+ * @param {string} [params.url] service에서 주입한 token API 경로
+ * @returns {UseQueryResult<API_Res_CctvRtcToken>} RTC token query 결과
+ */
 export const useQueryCctvRtcToken = ({
   company_id,
   cam_id,
+  enabled = true,
   username,
   url,
 }: API_Req_CctvRtcToken & {
+  enabled?: boolean;
   url?: string;
 }): UseQueryResult<API_Res_CctvRtcToken> =>
   useQuery({
+    // token은 username/company/cam/API route 조합별로 분리한다.
     queryKey: ["cctv_rtc_token", username, company_id, cam_id, url],
     queryFn: () => postCctvRtcToken({ company_id, cam_id, username, url }),
-    enabled: Boolean(username && company_id && cam_id),
+    // scheduler grant 전에는 token burst가 생기지 않도록 enabled를 false로 유지한다.
+    enabled: enabled && Boolean(username && company_id && cam_id),
+    // exp decode가 불가한 token은 fallback age를 넘기면 신규 WHEP 연결에 쓰지 않는다.
     staleTime: CCTV_RTC_TOKEN_FALLBACK_MAX_AGE_MS,
     gcTime: CCTV_RTC_TOKEN_GC_TIME_MS,
+    retry: shouldRetryCctvRtcTokenQuery,
+    // focus/reconnect/mount가 곧바로 다수 WHEP 재협상으로 이어지지 않도록 자동 refetch를 막는다.
     refetchOnMount: false,
     refetchOnReconnect: false,
     refetchOnWindowFocus: false,

package/src/cctv/components/Provider.tsx

@@ -14,6 +14,10 @@ import {
   createCctvRtcStreamRegistry,
   type CctvRtcStreamRegistry,
 } from "../hooks/streamRegistry";
+import {
+  createCctvRtcStreamScheduler,
+  type CctvRtcStreamScheduler,
+} from "../hooks/streamScheduler";
 
 /**
  * CCTV; API 경로 컨텍스트
@@ -28,6 +32,9 @@ const ApiUrlContext = createContext<CctvApiUrlContext>({
 const RtcStreamRegistryContext = createContext<CctvRtcStreamRegistry | null>(
   null,
 );
+const RtcStreamSchedulerContext = createContext<CctvRtcStreamScheduler | null>(
+  null,
+);
 
 /**
  * CCTV; API 경로 컨텍스트
@@ -40,6 +47,13 @@ export function useCctvApiUrl(): CctvApiUrlContext {
   return useContext(ApiUrlContext);
 }
 
+/**
+ * CCTV; RTC stream registry context hook
+ * @hook
+ * @returns {CctvRtcStreamRegistry} Provider instance 단위 stream registry
+ * @desc
+ * registry는 WHEP PeerConnection/MediaStream을 Provider lifecycle 안에서 유지하고 list/viewer video reattach를 담당한다.
+ */
 export function useCctvRtcStreamRegistry(): CctvRtcStreamRegistry {
   const registry = useContext(RtcStreamRegistryContext);
   if (!registry) {
@@ -50,6 +64,23 @@ export function useCctvRtcStreamRegistry(): CctvRtcStreamRegistry {
   return registry;
 }
 
+/**
+ * CCTV; RTC stream scheduler context hook
+ * @hook
+ * @returns {CctvRtcStreamScheduler} Provider instance 단위 stream scheduler
+ * @desc
+ * scheduler는 item UI 렌더와 token/WHEP 시작 시점을 분리해 초기 요청 burst를 batch 단위로 줄인다.
+ */
+export function useCctvRtcStreamScheduler(): CctvRtcStreamScheduler {
+  const scheduler = useContext(RtcStreamSchedulerContext);
+  if (!scheduler) {
+    throw new Error(
+      "CCTV.Provider 내부에서 useCctvRtcStreamScheduler를 사용해야 합니다.",
+    );
+  }
+  return scheduler;
+}
+
 /**
  * CCTV; Provider props
  * @component
@@ -60,6 +91,7 @@ export function useCctvRtcStreamRegistry(): CctvRtcStreamRegistry {
  * @property {string} [username] CCTV 조회시 권한 확인을 위한 계정명
  * @property {string} [whepUsername] WHEP endpoint username 덮어쓰기 값
  * @property {ContextExtension} [defaultValues] 서비스 확장 context 기본값
+ * @property {CctvRtcStreamOptions} [streamOptions] stream lazy loading 옵션
  * @property {React.ReactNode} children
  */
 export default function CCTVProvider<ContextExtension extends object = object>({
@@ -70,15 +102,39 @@ export default function CCTVProvider<ContextExtension extends object = object>({
   listUrl,
   tokenUrl,
   defaultValues,
+  streamOptions,
   children,
 }: CctvProviderProps<ContextExtension>) {
+  // streamOptions object identity가 매 렌더 바뀌어도 primitive option 값 기준으로만 scheduler를 교체한다.
+  const streamBatchSize = streamOptions?.batchSize;
+  const streamBatchIntervalMs = streamOptions?.batchIntervalMs;
+  const hasStreamOptions =
+    streamBatchSize !== undefined || streamBatchIntervalMs !== undefined;
+
+  // registry는 Provider lifetime 동안 유지해 list/viewer 전환 시 기존 MediaStream을 재사용한다.
   const streamRegistry = useMemo(() => createCctvRtcStreamRegistry(), []);
 
+  // scheduler는 Provider option이 바뀌는 경우에만 새 batch 정책으로 다시 만든다.
+  const streamScheduler = useMemo(
+    () =>
+      createCctvRtcStreamScheduler(
+        hasStreamOptions
+          ? {
+              batchIntervalMs: streamBatchIntervalMs,
+              batchSize: streamBatchSize,
+            }
+          : undefined,
+      ),
+    [hasStreamOptions, streamBatchIntervalMs, streamBatchSize],
+  );
+
   useEffect(() => {
     return () => {
+      // Provider unmount가 CCTV stream lifecycle의 최종 정리 지점이다.
       streamRegistry.closeAll();
+      streamScheduler.clear();
     };
-  }, [streamRegistry]);
+  }, [streamRegistry, streamScheduler]);
 
   const mergedDefaultValues = {
     // 변경 설명: service 확장 context 기본값을 core CCTV form context와 한 RHF scope에서 병합한다.
@@ -93,13 +149,15 @@ export default function CCTVProvider<ContextExtension extends object = object>({
   return (
     <ApiUrlContext.Provider value={{ listUrl, tokenUrl }}>
       <RtcStreamRegistryContext.Provider value={streamRegistry}>
-        <Form.Provider<CctvContext<ContextExtension>>
-          options={{
-            defaultValues: mergedDefaultValues,
-          }}
-        >
-          {children}
-        </Form.Provider>
+        <RtcStreamSchedulerContext.Provider value={streamScheduler}>
+          <Form.Provider<CctvContext<ContextExtension>>
+            options={{
+              defaultValues: mergedDefaultValues,
+            }}
+          >
+            {children}
+          </Form.Provider>
+        </RtcStreamSchedulerContext.Provider>
       </RtcStreamRegistryContext.Provider>
     </ApiUrlContext.Provider>
   );

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

@@ -25,8 +25,10 @@ export default function CCTVCamListItem({
   renderOverlay,
   ...cam
 }: CctvCamListItemProps) {
+  // item은 즉시 렌더하지만 token/WHEP 시작은 hook 내부 scheduler grant 이후로 지연된다.
   const { videoRef, ...rtcCtx } = useCctvRtcStream({ cam });
 
+  // live/error/message는 video-state util 하나를 기준으로 계산해 CamList와 Viewer 표시 규칙을 맞춘다.
   const isLive = useMemo(() => getIsLive({ cam, ...rtcCtx }), [cam, rtcCtx]);
   const isError = useMemo(() => getIsError({ cam, ...rtcCtx }), [cam, rtcCtx]);
   const overlayMessage = useMemo(
@@ -44,9 +46,11 @@ export default function CCTVCamListItem({
       )}
     >
       <CCTVVideoTemplate
+        // hook이 반환한 ref에 registry MediaStream이 attach된다.
         ref={videoRef}
         cam={cam}
         className="cctv-cam-list-video-container"
+        // list card에서는 live/share 상태를 header에 노출하고 제목은 footer로 내려 보낸다.
         headerOptions={{
           activeLiveState: true,
           activeTitle: false,
@@ -58,9 +62,11 @@ export default function CCTVCamListItem({
         // 변경 설명: list item custom overlay는 template seam 하나만 따라간다.
         renderOverlay={renderOverlay}
         {...{
+          // Video.Template이 overlay/body/footer를 한 번에 판단할 수 있도록 stream 상태를 함께 넘긴다.
           isError,
           overlayMessage,
           isLive,
+          streamStage: rtcCtx.streamStage,
           canReconnect: rtcCtx.canReconnect,
           reconnectStream: rtcCtx.reconnectStream,
         }}

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

@@ -11,14 +11,29 @@ import {
   getIsError,
 } from "../../../utils/video-state";
 
+/**
+ * CCTV; pagination list item
+ * @component
+ * @param {object} props
+ * @param {string} [props.className] pagination thumbnail item 클래스
+ * @param {string} props.cam_id 카메라 id코드
+ * @param {string} props.cam_name 카메라명
+ * @param {string} props.company_id 업체 id코드
+ * @param {boolean} props.cam_online 카메라 온라인 여부
+ * @param {string} props.cam_rtc WebRTC endpoint base URL
+ * @desc
+ * viewer 하단 thumbnail에서도 동일한 `useCctvRtcStream` 경로를 사용해 list/viewer 전환 시 registry reattach 계약을 유지한다.
+ */
 export default function CCTVPaginationListItem({
   className,
   ...cam
 }: {
   className?: string;
 } & CctvCompanyCameraData) {
+  // thumbnail은 즉시 렌더하고, 실제 token/WHEP 시작은 Provider scheduler가 batch 단위로 grant한다.
   const { videoRef, ...rtcCtx } = useCctvRtcStream({ cam });
 
+  // CamList item과 동일한 util을 사용해 overlay 상태 판정 drift를 막는다.
   const isLive = useMemo(() => getIsLive({ cam, ...rtcCtx }), [cam, rtcCtx]);
   const isError = useMemo(() => getIsError({ cam, ...rtcCtx }), [cam, rtcCtx]);
   const overlayMessage = useMemo(
@@ -26,6 +41,7 @@ export default function CCTVPaginationListItem({
     [cam, rtcCtx],
   );
 
+  // cam.onSelect는 render data에 주입된 선택 handler라 있을 때만 호출한다.
   const handleSelect = useCallback(() => {
     if (typeof cam.onSelect === "function") cam.onSelect();
   }, [cam]);
@@ -47,9 +63,11 @@ export default function CCTVPaginationListItem({
         aria-label={`${cam.cam_name} 선택`}
       >
         <CCTVVideoTemplate
+          // registry가 같은 streamKey의 MediaStream을 thumbnail video에 attach한다.
           ref={videoRef}
           cam={cam}
           className="cctv-pagination-list-video-container"
+          // thumbnail에서는 header live/share 상태만 보이고 footer action은 최소화한다.
           headerOptions={{
             activeLiveState: true,
             activeTitle: false,
@@ -59,9 +77,11 @@ export default function CCTVPaginationListItem({
           }}
           footerOptions={{ cam }}
           {...{
+            // Video.Template overlay가 queued/token-loading/connecting/error 상태를 통합 표시한다.
             isError,
             overlayMessage,
             isLive,
+            streamStage: rtcCtx.streamStage,
             canReconnect: rtcCtx.canReconnect,
             reconnectStream: rtcCtx.reconnectStream,
           }}

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

@@ -17,6 +17,7 @@ import type { CctvVideoTemplateProps } from "../../types/props";
  * @property {boolean} [isError]
  * @property {React.ReactNode} [overlayMessage]
  * @property {boolean} [isLive]
+ * @property {CctvRtcStreamStage} [streamStage]
  * @property {CctvCompanyCameraData} [cam]
  * @property {boolean} [canReconnect]
  * @property {CctvRtcReconnectTrigger} [reconnectStream]
@@ -33,6 +34,7 @@ const CCTVVideoTemplate = forwardRef<HTMLVideoElement, CctvVideoTemplateProps>(
       isError,
       isLive,
       overlayMessage,
+      streamStage,
       canReconnect,
       reconnectStream,
       renderOverlay,
@@ -60,6 +62,7 @@ const CCTVVideoTemplate = forwardRef<HTMLVideoElement, CctvVideoTemplateProps>(
             isError,
             isLive,
             overlayMessage,
+            streamStage,
             canReconnect,
             reconnectStream,
           })

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

@@ -61,6 +61,7 @@ export default function CCTVViewerDesktopVideo({
         isError,
         overlayMessage,
         isLive,
+        streamStage: rtcCtx.streamStage,
         canReconnect: rtcCtx.canReconnect,
         reconnectStream: rtcCtx.reconnectStream,
       }}